@constructive-io/express-context 0.26.1 → 0.27.0

package/refusals.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRecordRefusalsSink = exports.RefusalRecorder = exports.DEFAULT_REFUSAL_MAX_KEYS = exports.DEFAULT_REFUSAL_FLUSH_JITTER_MS = exports.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = exports.refusalRows = exports.refusalOverflowKey = exports.refusalKeyOf = exports.sourceBucket = exports.OVERFLOW_ROUTE = exports.OVERFLOW_SOURCE = exports.UNKNOWN_SOURCE = exports.REFUSAL_REASONS = void 0;
+const logger_1 = require("@pgpmjs/logger");
+const pg_query_context_1 = require("pg-query-context");
+const usage_counter_1 = require("./usage-counter");
+const log = new logger_1.Logger('refusals');
+exports.REFUSAL_REASONS = [
+    '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'
+];
+/** `source_bucket` when the lane could not resolve an address. */
+exports.UNKNOWN_SOURCE = 'unknown';
+/** `source_bucket` / `route_key` of the fold-down entry once the counter is full. */
+exports.OVERFLOW_SOURCE = 'overflow';
+exports.OVERFLOW_ROUTE = '*';
+const MINUTE_MS = 60_000;
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/**
+ * 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`.
+ */
+const sourceBucket = (ip) => {
+    if (!ip)
+        return exports.UNKNOWN_SOURCE;
+    let addr = ip.trim();
+    if (addr.startsWith('[')) {
+        const end = addr.indexOf(']');
+        if (end === -1)
+            return exports.UNKNOWN_SOURCE;
+        addr = addr.slice(1, end);
+    }
+    const zone = addr.indexOf('%');
+    if (zone !== -1)
+        addr = addr.slice(0, zone);
+    if (addr.toLowerCase().startsWith('::ffff:')) {
+        const mapped = addr.slice('::ffff:'.length);
+        if (IPV4.test(mapped))
+            addr = mapped;
+    }
+    const v4 = IPV4.exec(addr);
+    if (v4) {
+        const octets = v4.slice(1, 5).map(Number);
+        if (octets.some((o) => o > 255))
+            return exports.UNKNOWN_SOURCE;
+        return `${octets[0]}.${octets[1]}.${octets[2]}.0/24`;
+    }
+    const groups = expandIpv6(addr);
+    if (!groups)
+        return exports.UNKNOWN_SOURCE;
+    return `${groups[0]}:${groups[1]}:${groups[2]}::/48`;
+};
+exports.sourceBucket = sourceBucket;
+/** The eight hextets of an IPv6 address, or null when it does not parse. */
+const expandIpv6 = (addr) => {
+    if (!/^[0-9a-fA-F:]+$/.test(addr) || addr.indexOf(':::') !== -1)
+        return null;
+    const halves = addr.split('::');
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(':') : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    const groups = [...head, ...Array(missing).fill('0'), ...tail];
+    if (groups.some((g) => g.length === 0 || g.length > 4))
+        return null;
+    return groups.map((g) => parseInt(g, 16).toString(16));
+};
+const minuteOf = (at) => Math.floor(at / MINUTE_MS) * MINUTE_MS;
+const refusalKeyOf = (key) => `${key.minuteBucket}\u0000${key.databaseId ?? ''}\u0000${key.lane}\u0000${key.reason}\u0000${key.routeKey}\u0000${key.sourceBucket}`;
+exports.refusalKeyOf = refusalKeyOf;
+/**
+ * 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.
+ */
+const refusalOverflowKey = (key) => ({
+    ...key,
+    routeKey: exports.OVERFLOW_ROUTE,
+    sourceBucket: exports.OVERFLOW_SOURCE
+});
+exports.refusalOverflowKey = refusalOverflowKey;
+/** Shape a drained batch for `record_refusals(jsonb)`. */
+const refusalRows = (entries) => entries.map(({ key, count, firstAt, lastAt }) => ({
+    minute_bucket: new Date(key.minuteBucket).toISOString(),
+    database_id: key.databaseId,
+    lane: key.lane,
+    reason: key.reason,
+    route_key: key.routeKey,
+    source_bucket: key.sourceBucket,
+    count,
+    first_seen_at: new Date(firstAt).toISOString(),
+    last_seen_at: new Date(lastAt).toISOString()
+}));
+exports.refusalRows = refusalRows;
+exports.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = 10_000;
+exports.DEFAULT_REFUSAL_FLUSH_JITTER_MS = 2_000;
+exports.DEFAULT_REFUSAL_MAX_KEYS = 2_000;
+const defaultOnError = (err, dropped) => {
+    const refusals = dropped.reduce((sum, e) => sum + e.count, 0);
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(`[refusals] flush failed; dropped ${refusals} refusals across ${dropped.length} keys: ${message}`);
+};
+/**
+ * `BoundedCounter<RefusalKey>` + `CounterFlusher` + a `record_refusals` sink.
+ * Construct one per process, `start()` it, `record()` from every refusal site,
+ * `stop()` on shutdown.
+ */
+class RefusalRecorder {
+    counter;
+    flusher;
+    recordFailures = 0;
+    constructor(opts) {
+        this.counter = new usage_counter_1.BoundedCounter({
+            maxKeys: opts.maxKeys ?? exports.DEFAULT_REFUSAL_MAX_KEYS,
+            keyOf: exports.refusalKeyOf,
+            overflowKey: exports.refusalOverflowKey
+        });
+        this.flusher = new usage_counter_1.CounterFlusher(this.counter, (entries) => opts.sink((0, exports.refusalRows)(entries)), {
+            intervalMs: opts.intervalMs ?? exports.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS,
+            jitterMs: opts.jitterMs ?? exports.DEFAULT_REFUSAL_FLUSH_JITTER_MS,
+            onError: opts.onError ?? defaultOnError
+        });
+    }
+    /**
+     * 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) {
+        try {
+            const at = refusal.at ?? Date.now();
+            this.counter.increment({
+                minuteBucket: minuteOf(at),
+                databaseId: refusal.databaseId,
+                lane: refusal.lane,
+                reason: refusal.reason,
+                routeKey: refusal.routeKey,
+                sourceBucket: (0, exports.sourceBucket)(refusal.sourceIp)
+            }, 1, at);
+        }
+        catch (err) {
+            this.recordFailures += 1;
+            const message = err instanceof Error ? err.message : String(err);
+            log.error(`[refusals] record failed (refusal still served): ${message}`);
+        }
+    }
+    start() {
+        this.flusher.start();
+    }
+    /** Final flush, then stop. */
+    stop() {
+        return this.flusher.stop();
+    }
+    /** Drain and write now; a sink failure is reported, never thrown. */
+    flush() {
+        return this.flusher.flush();
+    }
+    stats() {
+        return {
+            keys: this.counter.size,
+            overflowed: this.counter.overflowed,
+            recordFailures: this.recordFailures,
+            flusher: this.flusher.stats()
+        };
+    }
+}
+exports.RefusalRecorder = RefusalRecorder;
+const FUNCTION_NAME = /^[a-z_][a-z0-9_]*\.[a-z_][a-z0-9_]*$/;
+/**
+ * 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.
+ */
+const createRecordRefusalsSink = (opts) => {
+    const fn = opts.functionName ?? 'constructive_usage_private.record_refusals';
+    if (!FUNCTION_NAME.test(fn)) {
+        throw new Error(`createRecordRefusalsSink: invalid function name ${JSON.stringify(fn)}`);
+    }
+    const [schema, name] = fn.split('.');
+    const sql = `SELECT "${schema}"."${name}"($1::jsonb) AS recorded`;
+    return async (rows) => {
+        if (rows.length === 0)
+            return;
+        const claims = await opts.claims();
+        await (0, pg_query_context_1.withPgClient)(opts.pool, claims, async (client) => {
+            await client.query(sql, [JSON.stringify(rows)]);
+        });
+    };
+};
+exports.createRecordRefusalsSink = createRecordRefusalsSink;

package/request-protection.d.ts

@@ -0,0 +1,117 @@
+/**
+ * request-protection — platform bounds for the per-request protection settings.
+ *
+ * `database_settings` / `api_settings` carry a tenant's *preferences*; this
+ * module owns the numbers the platform will actually honour. The platform
+ * default and the hard ceiling are code constants rather than rows, so a
+ * tenant can never widen a bound by writing metadata: a setting is only ever
+ * read as a request to be *stricter* than the platform is.
+ *
+ *   effective = clamp(LEAST(api_override, database_setting) ?? default, floor, max)
+ *
+ * `LEAST` (not `COALESCE`) is what makes an API override lower-only: an API
+ * that asks for a 60s statement timeout under a database that says 10s gets
+ * 10s. The floor exists so a tenant cannot write a value that makes its own
+ * API unusable (a 0ms statement timeout), and the ceiling so it cannot raise
+ * one past what the shared cluster will absorb.
+ */
+/** Every request-protection bound, resolved to a value the runtime enforces. */
+export interface RequestProtection {
+    /** `statement_timeout` for the request's transaction. */
+    statementTimeoutMs: number;
+    /** `idle_in_transaction_session_timeout` for the request's transaction. */
+    idleInTransactionTimeoutMs: number;
+    /** `lock_timeout` for the request's transaction. */
+    lockTimeoutMs: number;
+    /** In-flight requests admitted per database, per replica. */
+    maxConcurrentRequests: number;
+    /** How long a request may wait for a concurrency slot. `0` never queues. */
+    maxQueueWaitMs: number;
+    /** Sustained request rate allowed one caller on one route. */
+    rateLimitRpm: number;
+    /** Burst allowance above `rateLimitRpm` within the same window. */
+    rateLimitBurst: number;
+    /** Deepest selection set accepted in an operation. */
+    maxQueryDepth: number;
+    /** Largest static cost accepted in an operation. */
+    maxQueryCost: number;
+    /** Largest `first`/`last` accepted on a connection. */
+    maxPageSize: number;
+    /** Largest request body accepted. */
+    maxRequestBytes: number;
+    /** Whether the schema answers introspection queries. */
+    enableIntrospection: boolean;
+}
+/** The numeric bounds — every field of {@link RequestProtection} but the flag. */
+export type NumericProtectionKey = Exclude<keyof RequestProtection, 'enableIntrospection'>;
+/** What the platform grants, and the window a tenant may move inside. */
+export interface ProtectionBound {
+    /** Applied when neither scope expresses a preference. */
+    default: number;
+    /** Lowest value a tenant can make effective — below this its API breaks. */
+    floor: number;
+    /** Highest value the platform honours, whatever metadata says. */
+    max: number;
+}
+/**
+ * The platform's own numbers. Deliberately constants: a ceiling stored next to
+ * the value it caps is a ceiling a tenant can edit.
+ */
+export declare const PROTECTION_BOUNDS: Record<NumericProtectionKey, ProtectionBound>;
+/**
+ * What a connection with no `first`/`last` is charged.
+ *
+ * Such a field is unbounded in principle, so charging it the tenant's
+ * `maxPageSize` would make a large ceiling self-defeating: raising the page
+ * size a client *may* ask for would shrink the query it can write. A fixed
+ * estimate keeps the two bounds independent.
+ */
+export declare const ASSUMED_PAGE_SIZE = 100;
+/**
+ * Introspection stays on until metadata says otherwise, and `platformAllows`
+ * is the kill switch that takes it away cluster-wide regardless.
+ *
+ * The platform default is permissive here where the metadata default is not
+ * (`database_settings.enable_introspection` is `NOT NULL DEFAULT false`) on
+ * purpose: this value applies to a database that has expressed *no*
+ * preference — typically one whose routing plane predates the column — and
+ * silently disabling introspection for it would break GraphiQL and codegen for
+ * every tenant the moment this code deployed, without anyone opting in.
+ */
+export declare const INTROSPECTION_BOUND: {
+    default: boolean;
+    platformAllows: boolean;
+};
+/** What a database with no settings row gets. */
+export declare const DEFAULT_REQUEST_PROTECTION: RequestProtection;
+/**
+ * One scope's stored preferences. Every field is nullable — `null` is "no
+ * preference at this scope", which is why the resolver never treats a missing
+ * value as a zero.
+ */
+export interface RequestProtectionInput {
+    statementTimeoutMs?: number | null;
+    idleInTransactionTimeoutMs?: number | null;
+    lockTimeoutMs?: number | null;
+    maxConcurrentRequests?: number | null;
+    maxQueueWaitMs?: number | null;
+    rateLimitRpm?: number | null;
+    rateLimitBurst?: number | null;
+    maxQueryDepth?: number | null;
+    maxQueryCost?: number | null;
+    maxPageSize?: number | null;
+    maxRequestBytes?: number | null;
+    enableIntrospection?: boolean | null;
+}
+/**
+ * Resolve the bounds a request runs under.
+ *
+ * @param database - the `database_settings` row for the tenant, if any
+ * @param api - the `api_settings` overrides for the API the request arrived on
+ */
+export declare function resolveRequestProtection(database?: RequestProtectionInput | null, api?: RequestProtectionInput | null): RequestProtection;
+/**
+ * The timeout GUCs as `SET LOCAL` pairs, for merging into a request's
+ * pgSettings. PostgreSQL reads a bare integer for all three as milliseconds.
+ */
+export declare function protectionPgSettings(protection: RequestProtection): Record<string, string>;

package/request-protection.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * request-protection — platform bounds for the per-request protection settings.
+ *
+ * `database_settings` / `api_settings` carry a tenant's *preferences*; this
+ * module owns the numbers the platform will actually honour. The platform
+ * default and the hard ceiling are code constants rather than rows, so a
+ * tenant can never widen a bound by writing metadata: a setting is only ever
+ * read as a request to be *stricter* than the platform is.
+ *
+ *   effective = clamp(LEAST(api_override, database_setting) ?? default, floor, max)
+ *
+ * `LEAST` (not `COALESCE`) is what makes an API override lower-only: an API
+ * that asks for a 60s statement timeout under a database that says 10s gets
+ * 10s. The floor exists so a tenant cannot write a value that makes its own
+ * API unusable (a 0ms statement timeout), and the ceiling so it cannot raise
+ * one past what the shared cluster will absorb.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REQUEST_PROTECTION = exports.INTROSPECTION_BOUND = exports.ASSUMED_PAGE_SIZE = exports.PROTECTION_BOUNDS = void 0;
+exports.resolveRequestProtection = resolveRequestProtection;
+exports.protectionPgSettings = protectionPgSettings;
+// ─── Platform bounds ────────────────────────────────────────────────────────
+/**
+ * The platform's own numbers. Deliberately constants: a ceiling stored next to
+ * the value it caps is a ceiling a tenant can edit.
+ */
+exports.PROTECTION_BOUNDS = {
+    statementTimeoutMs: { default: 30_000, floor: 1_000, max: 120_000 },
+    idleInTransactionTimeoutMs: { default: 60_000, floor: 1_000, max: 300_000 },
+    lockTimeoutMs: { default: 5_000, floor: 100, max: 60_000 },
+    maxConcurrentRequests: { default: 50, floor: 1, max: 500 },
+    maxQueueWaitMs: { default: 5_000, floor: 0, max: 60_000 },
+    rateLimitRpm: { default: 600, floor: 1, max: 60_000 },
+    rateLimitBurst: { default: 60, floor: 1, max: 10_000 },
+    maxQueryDepth: { default: 12, floor: 1, max: 50 },
+    // Cost is measured in rows a document can pull (see ASSUMED_PAGE_SIZE), so
+    // the default has to leave room for the nesting Graphile encourages while
+    // still refusing the millions-of-rows shapes.
+    maxQueryCost: { default: 1_000_000, floor: 100, max: 100_000_000 },
+    maxPageSize: { default: 1_000, floor: 1, max: 10_000 },
+    maxRequestBytes: { default: 1_000_000, floor: 1_024, max: 10_000_000 }
+};
+/**
+ * What a connection with no `first`/`last` is charged.
+ *
+ * Such a field is unbounded in principle, so charging it the tenant's
+ * `maxPageSize` would make a large ceiling self-defeating: raising the page
+ * size a client *may* ask for would shrink the query it can write. A fixed
+ * estimate keeps the two bounds independent.
+ */
+exports.ASSUMED_PAGE_SIZE = 100;
+/**
+ * Introspection stays on until metadata says otherwise, and `platformAllows`
+ * is the kill switch that takes it away cluster-wide regardless.
+ *
+ * The platform default is permissive here where the metadata default is not
+ * (`database_settings.enable_introspection` is `NOT NULL DEFAULT false`) on
+ * purpose: this value applies to a database that has expressed *no*
+ * preference — typically one whose routing plane predates the column — and
+ * silently disabling introspection for it would break GraphiQL and codegen for
+ * every tenant the moment this code deployed, without anyone opting in.
+ */
+exports.INTROSPECTION_BOUND = {
+    default: true,
+    platformAllows: true
+};
+/** What a database with no settings row gets. */
+exports.DEFAULT_REQUEST_PROTECTION = resolveDefaults();
+function resolveDefaults() {
+    const numeric = Object.fromEntries(Object.entries(exports.PROTECTION_BOUNDS).map(([key, bound]) => [key, bound.default]));
+    return { ...numeric, enableIntrospection: exports.INTROSPECTION_BOUND.default };
+}
+// ─── Resolution ─────────────────────────────────────────────────────────────
+const clamp = (value, bound) => Math.min(Math.max(value, bound.floor), bound.max);
+/** The stricter of two preferences, ignoring the scopes that expressed none. */
+const strictest = (a, b) => {
+    const values = [a, b].filter((v) => typeof v === 'number' && Number.isFinite(v));
+    return values.length > 0 ? Math.min(...values) : null;
+};
+/**
+ * Resolve the bounds a request runs under.
+ *
+ * @param database - the `database_settings` row for the tenant, if any
+ * @param api - the `api_settings` overrides for the API the request arrived on
+ */
+function resolveRequestProtection(database, api) {
+    const resolved = {};
+    for (const [name, bound] of Object.entries(exports.PROTECTION_BOUNDS)) {
+        const preferred = strictest(database?.[name], api?.[name]);
+        resolved[name] = clamp(preferred ?? bound.default, bound);
+    }
+    // Lower-only applies to the flag too: an API may switch introspection off
+    // for itself, never back on for a database that turned it off, and the
+    // platform switch can only ever take it away.
+    const enableIntrospection = (database?.enableIntrospection ?? exports.INTROSPECTION_BOUND.default) &&
+        (api?.enableIntrospection ?? true) &&
+        exports.INTROSPECTION_BOUND.platformAllows;
+    return { ...resolved, enableIntrospection };
+}
+/**
+ * The timeout GUCs as `SET LOCAL` pairs, for merging into a request's
+ * pgSettings. PostgreSQL reads a bare integer for all three as milliseconds.
+ */
+function protectionPgSettings(protection) {
+    return {
+        statement_timeout: String(protection.statementTimeoutMs),
+        idle_in_transaction_session_timeout: String(protection.idleInTransactionTimeoutMs),
+        lock_timeout: String(protection.lockTimeoutMs)
+    };
+}

package/types.d.ts

@@ -8,6 +8,7 @@
  */
 import type { Pool, PoolClient } from 'pg';
 import type { BillingClient } from './billing-client';
+import type { RequestProtection } from './request-protection';
 export interface DatabaseSettings {
     enableAggregates: boolean;
     enablePostgis: boolean;
@@ -226,6 +227,7 @@ export interface BuiltinModuleMap {
     agentChat: AgentChatConfig;
     llm: LlmConfig;
     compute: ComputeConfig;
+    requestProtection: RequestProtection;
 }
 /**
  * Callback for executing queries within a tenant-scoped transaction

package/usage-counter.d.ts

@@ -0,0 +1,137 @@
+/**
+ * usage-counter — the shared in-memory count + batch-flush mechanism.
+ *
+ * Two classes, neither of which knows what is being counted:
+ *
+ *   - `BoundedCounter<K>` is the map. Consumers pass the key type, how a key
+ *     serialises (`keyOf`) and where a key folds to once the map is full
+ *     (`overflowKey`). `increment` is O(1), synchronous and never throws, so a
+ *     request path can call it while refusing traffic without ever waiting on,
+ *     or being affected by, whatever eventually stores the counts.
+ *   - `CounterFlusher<K>` is the loop. It drains the counter on a jittered
+ *     interval, hands the batch to a `sink`, and owns the failure policy: a
+ *     batch the sink cannot write is reported through `onError` *and dropped*.
+ *     Re-queuing under a broken sink is how a bounded counter becomes an
+ *     unbounded one, and the counter is already accumulating the next window.
+ *
+ * Refusal observability instantiates these with a refusal key and a sink that
+ * calls `constructive_usage_private.record_refusals` (see `refusals.ts`); the
+ * page/request metering lane instantiates the same two classes with its own
+ * `K`, `keyOf`, `overflowKey`, bound, interval and sink. The seam is the
+ * constructor arguments — nothing in this file is specific to either.
+ *
+ * Counters live in process memory only. A crash loses at most one interval's
+ * worth of counts; `stop()` flushes on graceful shutdown. That is deliberate:
+ * the alternative is a durable write per event, which is the thing counting in
+ * memory exists to avoid.
+ *
+ * @module usage-counter
+ */
+export interface CounterEntry<K> {
+    key: K;
+    /** Sum of every `by` since this entry was created (or last drained). */
+    count: number;
+    /** Earliest `at` folded into this entry. */
+    firstAt: number;
+    /** Latest `at` folded into this entry. */
+    lastAt: number;
+}
+export interface BoundedCounterOptions<K> {
+    /**
+     * Distinct keys the counter will hold between drains. Past this, a *new* key
+     * is replaced by `overflowKey(key)` before it is counted; keys already
+     * present keep incrementing. Overflow keys are always admitted, so the true
+     * ceiling is `maxKeys` plus the number of distinct overflow keys the
+     * consumer's `overflowKey` can produce — keep that small.
+     */
+    maxKeys: number;
+    /** Serialise a key. Two keys with the same string share one entry. */
+    keyOf: (key: K) => string;
+    /**
+     * Where a key folds to once the map is full. Should collapse the
+     * high-cardinality parts of the key (a source address, a route) while
+     * keeping the attribution the consumer cannot afford to lose.
+     */
+    overflowKey: (key: K) => K;
+}
+export declare class BoundedCounter<K> {
+    private readonly entries;
+    private overflowedSinceDrain;
+    private readonly maxKeys;
+    private readonly keyOf;
+    private readonly overflowKey;
+    constructor(opts: BoundedCounterOptions<K>);
+    /** Distinct keys currently held. */
+    get size(): number;
+    /** Increments folded into an overflow key since the last drain. */
+    get overflowed(): number;
+    /**
+     * Add `by` to `key`. Synchronous, O(1), never throws for a well-formed
+     * `keyOf`/`overflowKey`; the caller's request path must not depend on it in
+     * any other way.
+     */
+    increment(key: K, by?: number, at?: number): void;
+    /**
+     * Return every entry and start a fresh window. The returned array is the
+     * only reference to those entries, so a slow sink never contends with the
+     * hot path.
+     */
+    drain(): CounterEntry<K>[];
+}
+export type CounterSink<K> = (entries: CounterEntry<K>[]) => Promise<void>;
+export interface CounterFlusherOptions<K> {
+    /** Base time between flushes. */
+    intervalMs: number;
+    /**
+     * Uniform random offset added to each interval so replicas started together
+     * do not hit the store on the same tick.
+     */
+    jitterMs: number;
+    /**
+     * Called for every failed flush with the batch that was dropped. Every
+     * failure is reported — there is no "log once then go quiet" — and the
+     * request path is not involved, so making this loud is free.
+     */
+    onError: (err: unknown, dropped: CounterEntry<K>[]) => void;
+}
+export interface CounterFlusherStats {
+    /** Epoch ms of the last flush attempt that returned without error, or null. */
+    lastFlushAt: number | null;
+    /** Epoch ms of the last failed flush, or null. */
+    lastErrorAt: number | null;
+    /** Message of the last failed flush, or null. */
+    lastError: string | null;
+    /** Failed flushes since the last success. */
+    consecutiveFailures: number;
+    /** Entries handed to `onError` over the flusher's lifetime. */
+    droppedEntries: number;
+    /** Whether the timer is armed. */
+    running: boolean;
+}
+export declare class CounterFlusher<K> {
+    private readonly counter;
+    private readonly sink;
+    private readonly opts;
+    private timer;
+    private inFlight;
+    private running;
+    private lastFlushAt;
+    private lastErrorAt;
+    private lastError;
+    private consecutiveFailures;
+    private droppedEntries;
+    constructor(counter: BoundedCounter<K>, sink: CounterSink<K>, opts: CounterFlusherOptions<K>);
+    /** Arm the timer. Idempotent. The timer is unref'd so it never pins the process. */
+    start(): void;
+    /** Disarm the timer and flush whatever is pending. Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * Drain and write now. Never rejects: a sink failure goes to `onError`. If a
+     * flush is already in flight the call waits for it and then runs its own, so
+     * two overlapping timers cannot send batches out of order.
+     */
+    flush(): Promise<void>;
+    stats(): CounterFlusherStats;
+    private arm;
+    private flushOnce;
+}