hippo-memory 2.0.0 → 2.1.0

package/dist/server/cursor.d.ts

@@ -4,15 +4,22 @@ type CursorPart = 'string' | 'integer';
 /** Bare-array routes cannot grow a body field without breaking clients, so their next cursor rides this header. */
 export declare const NEXT_CURSOR_HEADER = "X-Next-Cursor";
 export declare function encodeCursor(pos: KeysetPosition): string;
-/** The position a `?cursor=` names, or undefined when the param is absent; anything this server did not mint is a 400. */
+/**
+ * The position a `?cursor=` names, or undefined when the param is absent; anything this server did not mint is a 400.
+ */
 export declare function parseCursor(raw: string | null, keyPart: CursorPart, idPart: CursorPart): KeysetPosition | undefined;
 export interface Page<T> {
     items: T[];
     nextCursor: string | null;
 }
-/** Drops the one-row lookahead the query fetched past `limit` and names the next page's cursor, null on the last page. */
+/**
+ * Drops the one-row lookahead the query fetched past `limit` and names the next page's cursor, null on the last page.
+ */
 export declare function pageOf<T>(rows: readonly T[], limit: number, positionOf: (row: T) => KeysetPosition): Page<T>;
-/** Rows ordered by (created_at DESC, id DESC): the decision, incident, process, policy, skill, brief, note and prediction tables. */
+/**
+ * Rows ordered by (created_at DESC, id DESC): the decision, incident, process, policy, skill, brief, note and
+ * prediction tables.
+ */
 export declare function byCreatedAt(row: {
     createdAt: string;
     id: number;

package/dist/server/cursor.js

@@ -29,7 +29,9 @@ function toPosition(parsed, keyPart, idPart) {
     const [key, id] = parsed;
     return isPart(key, keyPart) && isPart(id, idPart) ? { key, id } : undefined;
 }
-/** The position a `?cursor=` names, or undefined when the param is absent; anything this server did not mint is a 400. */
+/**
+ * The position a `?cursor=` names, or undefined when the param is absent; anything this server did not mint is a 400.
+ */
 export function parseCursor(raw, keyPart, idPart) {
     if (raw === null)
         return undefined;
@@ -39,14 +41,19 @@ export function parseCursor(raw, keyPart, idPart) {
         throw new HttpError(400, 'cursor is malformed; pass next_cursor from the previous page unchanged');
     return pos;
 }
-/** Drops the one-row lookahead the query fetched past `limit` and names the next page's cursor, null on the last page. */
+/**
+ * Drops the one-row lookahead the query fetched past `limit` and names the next page's cursor, null on the last page.
+ */
 export function pageOf(rows, limit, positionOf) {
     if (rows.length <= limit)
         return { items: [...rows], nextCursor: null };
     const items = rows.slice(0, limit);
     return { items, nextCursor: encodeCursor(positionOf(items[items.length - 1])) };
 }
-/** Rows ordered by (created_at DESC, id DESC): the decision, incident, process, policy, skill, brief, note and prediction tables. */
+/**
+ * Rows ordered by (created_at DESC, id DESC): the decision, incident, process, policy, skill, brief, note and
+ * prediction tables.
+ */
 export function byCreatedAt(row) {
     return { key: row.createdAt, id: row.id };
 }

package/dist/server/deadline.d.ts

@@ -6,6 +6,9 @@ export declare function handlerDeadlineCount(): number;
 export declare function isAbandoned(res: ServerResponse): boolean;
 /** The deadline of `req`, for every /v1 and /mcp route but the two exempt ones. */
 export declare function requestDeadlineFor(req: IncomingMessage): RequestDeadline | undefined;
-/** Calls `reply` when `res` has sent nothing by `deadline`. A store call still in flight answers first, since only the store knows what became of a write. */
-export declare function answerAtDeadline(res: ServerResponse, deadline: RequestDeadline, reply: () => void): void;
+/**
+ * Calls `reply` when `res` has sent nothing by `deadline`. A store call still in flight answers first, since only the
+ * store knows what became of a write.
+ */
+export declare function answerAtDeadline(res: ServerResponse, deadline: RequestDeadline, reply: () => void, onDeadline?: () => void): void;
 //# sourceMappingURL=deadline.d.ts.map

package/dist/server/deadline.js

@@ -19,8 +19,11 @@ export function requestDeadlineFor(req) {
         return undefined;
     return path.startsWith('/v1/') || path === '/mcp' ? new RequestDeadline(Date.now() + ms) : undefined;
 }
-/** Calls `reply` when `res` has sent nothing by `deadline`. A store call still in flight answers first, since only the store knows what became of a write. */
-export function answerAtDeadline(res, deadline, reply) {
+/**
+ * Calls `reply` when `res` has sent nothing by `deadline`. A store call still in flight answers first, since only the
+ * store knows what became of a write.
+ */
+export function answerAtDeadline(res, deadline, reply, onDeadline = () => { }) {
     const expire = () => {
         if (res.headersSent || res.destroyed)
             return;
@@ -29,7 +32,11 @@ export function answerAtDeadline(res, deadline, reply) {
         reply();
     };
     // One turn of the loop later, so a handler that fails on the store's answer sends that answer itself.
-    const timer = setTimeout(() => deadline.onceIdle(() => setImmediate(expire)), deadline.at - Date.now());
+    const timer = setTimeout(() => {
+        // Before the wait for store calls, so a call still queued is dropped rather than run for a caller who left.
+        onDeadline();
+        deadline.onceIdle(() => setImmediate(expire));
+    }, deadline.at - Date.now());
     // The open socket keeps the process alive; this timer alone must not.
     timer.unref();
     const clear = () => clearTimeout(timer);

package/dist/server/key-check-bounds.js

@@ -1,4 +1,5 @@
-// Bounds on the scrypt work a bearer key check may start: how many derive at once, and how many one address starts for one key id.
+// Bounds on the scrypt work a bearer key check may start: how many derive at once, and how many one address starts for
+// one key id.
 import { HttpError } from '../util/http-util.js';
 import { createRateLimiter } from './rate-limit.js';
 // libuv runs scrypt on a pool of four threads by default, so two stay free for file and DNS work.
@@ -12,14 +13,21 @@ const KEY_ADDRESS_TRIES_PER_SEC = 5 / 60;
 export function keyCheckBounds(maxKeys) {
     // A bucket idle for a full refill is back at its burst, so dropping it then gives nothing away.
     const idleEvictMs = (KEY_ADDRESS_BURST / KEY_ADDRESS_TRIES_PER_SEC) * 1000;
-    const perKeyAddress = createRateLimiter({ ratePerSec: KEY_ADDRESS_TRIES_PER_SEC, burst: KEY_ADDRESS_BURST, idleEvictMs, maxKeys });
+    const perKeyAddress = createRateLimiter({
+        ratePerSec: KEY_ADDRESS_TRIES_PER_SEC,
+        burst: KEY_ADDRESS_BURST,
+        idleEvictMs,
+        maxKeys,
+    });
     let inFlight = 0;
     const waiting = [];
     return {
         admit(keyId, address) {
-            // Each answers in the words an existing limit uses: the request limit's for a full queue, the address's scrypt bucket's for spent tries.
-            if (inFlight >= MAX_IN_FLIGHT && waiting.length >= MAX_WAITING)
+            // Each answers in the words an existing limit uses: the request limit's for a full queue, the address's scrypt
+            // bucket's for spent tries.
+            if (inFlight >= MAX_IN_FLIGHT && waiting.length >= MAX_WAITING) {
                 throw new HttpError(429, 'rate limit exceeded', 1);
+            }
             if (!perKeyAddress.check(`${keyId}\u0000${address}`)) {
                 throw new HttpError(429, 'too many key checks from this address', perKeyAddress.retryAfterSec);
             }

package/dist/server/lifecycle.d.ts

@@ -3,6 +3,9 @@ export declare function setKeepAliveTimeouts(server: Server): void;
 export declare const DEFAULT_SHUTDOWN_DRAIN_MS = 5000;
 /** How long a signal or crash shutdown may run before the process is ended without it. */
 export declare function shutdownBoundMs(drainMs: number): number;
-/** Stops accepting, ends streams at once (they never finish on their own), gives other in-flight requests up to `drainMs`, then closes what is left. */
+/**
+ * Stops accepting, ends streams at once (they never finish on their own), gives other in-flight requests up to
+ * `drainMs`, then closes what is left.
+ */
 export declare function drainAndClose(server: Server, inflight: ReadonlySet<ServerResponse>, drainMs: number): Promise<void>;
 //# sourceMappingURL=lifecycle.d.ts.map

package/dist/server/lifecycle.js

@@ -1,23 +1,29 @@
 import { bodyDeadlineMs } from '../util/http-util.js';
 import { log } from '../util/log.js';
-// Node's own default, named so the three socket deadlines read together. It times the request arriving, never the handler, so a 10 minute sleep is not cut.
+// Node's own default, named so the three socket deadlines read together. It times the request arriving, never the
+// handler, so a 10 minute sleep is not cut.
 const REQUEST_RECEIVE_TIMEOUT_MS = 300_000;
 export function setKeepAliveTimeouts(server) {
     // The default 5s keepAliveTimeout closes idle sockets just as clients reuse them (ECONNRESET).
-    // headersTimeout must stay ABOVE keepAliveTimeout + keepAliveTimeoutBuffer (1s), or it closes idle reused sockets itself.
+    // headersTimeout must stay ABOVE keepAliveTimeout + keepAliveTimeoutBuffer (1s), or it closes idle reused sockets
+    // itself.
     server.keepAliveTimeout = 65_000;
     server.headersTimeout = 70_000;
     // Never below what a raised body deadline allows, or Node's bare 408 would come before the route's own.
     server.requestTimeout = Math.max(REQUEST_RECEIVE_TIMEOUT_MS, server.headersTimeout + bodyDeadlineMs());
 }
 export const DEFAULT_SHUTDOWN_DRAIN_MS = 5000;
-// Past the request drain, a stop only waits for each store thread to end its statement and close: seconds at most, so longer means a thread that will not end.
+// Past the request drain, a stop only waits for each store thread to end its statement and close: seconds at most, so
+// longer means a thread that will not end.
 const STORE_CLOSE_GRACE_MS = 10_000;
 /** How long a signal or crash shutdown may run before the process is ended without it. */
 export function shutdownBoundMs(drainMs) {
     return drainMs + STORE_CLOSE_GRACE_MS;
 }
-/** Stops accepting, ends streams at once (they never finish on their own), gives other in-flight requests up to `drainMs`, then closes what is left. */
+/**
+ * Stops accepting, ends streams at once (they never finish on their own), gives other in-flight requests up to
+ * `drainMs`, then closes what is left.
+ */
 export async function drainAndClose(server, inflight, drainMs) {
     const closed = new Promise((resolve, reject) => {
         server.close((err) => (err ? reject(err) : resolve()));

package/dist/server/mcp-http.d.ts

@@ -1,7 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { CallerProject } from '../api/prompt-hook.js';
 import type { ResolvedServeOpts } from './types.js';
-/** On a shared store, the caller's project from X-Hippo-Project and the comma-separated X-Hippo-Project-Aliases; any other store ignores both. */
+/** On a shared store, the caller's project from X-Hippo-Project and the comma-separated X-Hippo-Project-Aliases; any
+ * other store ignores both. */
 export declare function callerProjectFromHeaders(req: IncomingMessage, hippoRoot: string): CallerProject | undefined;
 export declare function handleMcpPost(req: IncomingMessage, res: ServerResponse, opts: ResolvedServeOpts): Promise<void>;
 export declare function handleMcpStream(req: IncomingMessage, res: ServerResponse, opts: ResolvedServeOpts, streamSlots: Map<string, number>): Promise<void>;

package/dist/server/mcp-http.js

@@ -3,18 +3,19 @@ import { envMcpSseHeartbeatMs, envMcpSseMaxAgeSec, envMcpSseMaxStreams } from '.
 import { isSharedStore } from '../core/config.js';
 import { handleMcpRequest, mcpErrorResponse } from '../mcp/server.js';
 import { HttpError, readBody, sendJson } from '../util/http-util.js';
-import { log } from '../util/log.js';
+import { errorFields, log } from '../util/log.js';
 import { assertCallerProject } from '../core/project-identity.js';
 import { buildContextWithAuth, heartbeatVerdict, readAuthHeader, requireAuth } from './auth.js';
 import { clientLimitKey } from './client-ip.js';
 import { noteAccess } from './request.js';
 import { isJsonString, isJsonObject } from '../util/json.js';
 import { blockHash } from '../util/token-text.js';
+import { MINUTE_MS } from '../util/time.js';
 import { consolidateInChild } from './sleep-offload.js';
-const DEFAULT_SSE_HEARTBEAT_MS = 60_000;
+const DEFAULT_SSE_HEARTBEAT_MS = MINUTE_MS;
 const DEFAULT_SSE_MAX_AGE_SEC = 3600;
-/** Per-client key for MCP state isolation under HTTP-MCP (scopes `lastRecalledIds`): sha256 of the token (16 hex chars, so the raw bearer is never logged)
- * plus the client address the rate limiter keys on, so clients sharing a key stay separable behind a trusted proxy too; 'noauth' covers loopback no-auth. */
+/** Per-client key for MCP state isolation under HTTP-MCP (scopes `lastRecalledIds`): sha256 of the token (16 hex chars,
+ * so the raw bearer is never logged) plus the client address the rate limiter keys on; 'noauth' covers loopback. */
 function buildMcpClientKey(req) {
     const auth = readAuthHeader(req);
     const tokenHash = auth.kind === 'bearer'
@@ -23,8 +24,8 @@ function buildMcpClientKey(req) {
     return `http:${tokenHash}:${clientLimitKey(req)}`;
 }
 // MCP-over-HTTP/SSE: POST /mcp answers a JSON-RPC request synchronously; GET /mcp/stream is a keepalive-only SSE stream
-// (`: ping` every DEFAULT_SSE_HEARTBEAT_MS, 60 s) in v1.
-// Both dispatch to handleMcpRequest as stdio does. Auth matches /v1/* (Bearer via `requireAuth`, loopback fallback); SSE is checked once at stream-open.
+// (`: ping` every DEFAULT_SSE_HEARTBEAT_MS, 60 s) in v1. Both dispatch to handleMcpRequest as stdio does. Auth matches
+// /v1/* (Bearer via `requireAuth`, loopback fallback); SSE is checked once at stream-open.
 // Percent-encoded by the client, so any lowercase Unicode name fits a Latin-1 header.
 const HEADER_PIECE = /^[A-Za-z0-9\-_.!~*'()%]+$/;
 function decodeHeaderPiece(raw, header) {
@@ -37,7 +38,8 @@ function decodeHeaderPiece(raw, header) {
         throw new HttpError(400, `${header} holds a bad percent escape`);
     }
 }
-/** On a shared store, the caller's project from X-Hippo-Project and the comma-separated X-Hippo-Project-Aliases; any other store ignores both. */
+/** On a shared store, the caller's project from X-Hippo-Project and the comma-separated X-Hippo-Project-Aliases; any
+ * other store ignores both. */
 export function callerProjectFromHeaders(req, hippoRoot) {
     if (!isSharedStore(hippoRoot))
         return undefined;
@@ -48,8 +50,9 @@ export function callerProjectFromHeaders(req, hippoRoot) {
             throw new HttpError(400, 'X-Hippo-Project-Aliases needs X-Hippo-Project');
         return undefined;
     }
-    if (names.length > 1 || (aliasHeaders?.length ?? 0) > 1)
+    if (names.length > 1 || (aliasHeaders?.length ?? 0) > 1) {
         throw new HttpError(400, 'send X-Hippo-Project and X-Hippo-Project-Aliases once each');
+    }
     const name = decodeHeaderPiece(names[0], 'X-Hippo-Project');
     const rawAliases = aliasHeaders?.[0] ?? '';
     const aliases = rawAliases === '' ? [] : rawAliases.split(',').map((a) => decodeHeaderPiece(a, 'X-Hippo-Project-Aliases'));
@@ -70,6 +73,7 @@ function mcpContextFor(ctx, clientKey, autoSleep, project) {
         owner: ctx.actor.owner,
         clientKey,
         store: ctx.store,
+        reach: ctx.reach,
         autoSleep,
         autoSleepRunner: consolidateInChild,
     };
@@ -78,8 +82,8 @@ function mcpContextFor(ctx, clientKey, autoSleep, project) {
     return mcpCtx;
 }
 export async function handleMcpPost(req, res, opts) {
-    // Same Context the /v1/* routes use, so MCP tool calls inherit the bound hippoRoot and the auth-resolved tenantId/actor; otherwise executeTool would walk
-    // from cwd and read HIPPO_TENANT, dropping a valid Bearer for tenant B to the env's tenant.
+    // Same Context the /v1/* routes use, so tool calls inherit the bound hippoRoot and the auth-resolved tenantId/actor;
+    // else executeTool walks from cwd and reads HIPPO_TENANT, dropping a valid Bearer for tenant B to the env's tenant.
     const ctx = await buildContextWithAuth(req, opts);
     noteAccess(req, { tenant: ctx.tenantId });
     const project = callerProjectFromHeaders(req, ctx.hippoRoot);
@@ -94,8 +98,8 @@ export async function handleMcpPost(req, res, opts) {
     if (!isJsonObject(mcpReq) || !isJsonString(mcpReq.method)) {
         throw new HttpError(400, 'JSON-RPC body must include a method string');
     }
-    // SAFETY: validated above as a plain JSON object with a string method; the other McpRequest wire fields (jsonrpc, id, params) are checked or defaulted in
-    // handleMcpRequest.
+    // SAFETY: validated above as a plain JSON object with a string method; the other McpRequest wire fields (jsonrpc, id,
+    // params) are checked or defaulted in handleMcpRequest.
     const rpcReq = mcpReq;
     let mcpRes;
     try {
@@ -127,8 +131,9 @@ function acquireStreamSlot(req, res, slots) {
     const max = envMcpSseMaxStreams() ?? DEFAULT_MAX_STREAMS_PER_CLIENT;
     const key = streamSlotKey(req);
     const open = slots.get(key) ?? 0;
-    if (open >= max)
+    if (open >= max) {
         throw new HttpError(429, `too many open streams for this client (limit ${max}); close one first`, 60);
+    }
     slots.set(key, open + 1);
     res.once('close', () => {
         const left = (slots.get(key) ?? 1) - 1;
@@ -152,8 +157,8 @@ export async function handleMcpStream(req, res, opts, streamSlots) {
     // Initial ping so smoke tests can confirm the stream is live without
     // waiting for the first keepalive interval.
     res.write(': ping\n\n');
-    // SSE hardening: the heartbeat re-validates the bearer (MCP_SSE_HEARTBEAT_MS, default 60000) and closes with 'auth_revoked' if the key was revoked or
-    // rotated; MCP_SSE_MAX_AGE_SEC (default 3600) caps stream lifetime and closes with 'max_age_exceeded'.
+    // SSE hardening: the heartbeat re-validates the bearer (MCP_SSE_HEARTBEAT_MS, default 60000) and closes with
+    // 'auth_revoked' if the key was revoked or rotated; MCP_SSE_MAX_AGE_SEC (default 3600) ends it as 'max_age_exceeded'.
     keepStreamAlive(req, res, opts);
 }
 function keepStreamAlive(req, res, opts) {
@@ -181,7 +186,7 @@ function keepStreamAlive(req, res, opts) {
         if (checking)
             return;
         checking = true;
-        void heartbeatVerdict(req, opts).then((verdict) => {
+        heartbeatVerdict(req, opts).then((verdict) => {
             checking = false;
             if (!closed && verdict === 'unavailable')
                 log.warn('heartbeat tick skipped: auth check unavailable');
@@ -192,12 +197,12 @@ function keepStreamAlive(req, res, opts) {
                 clearInterval(ping);
                 return;
             }
-            try {
-                res.write(': ping\n\n');
-            }
-            catch {
-                clearInterval(ping); // the client hung up; stop pinging a dead socket
-            }
+            if (!writePing(res))
+                clearInterval(ping);
+        }).catch((err) => {
+            // Without the reset `checking` stays true and the heartbeat never runs again.
+            checking = false;
+            log.warn('heartbeat tick failed', errorFields(err));
         });
     }, heartbeatMs);
     // Don't keep the event loop alive just for this timer — the server's
@@ -210,6 +215,16 @@ function keepStreamAlive(req, res, opts) {
         clearInterval(ping);
     });
 }
+/** False when the client hung up, so the caller stops pinging a dead socket. */
+function writePing(res) {
+    try {
+        res.write(': ping\n\n');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function endStreamWithReason(res, reason) {
     try {
         res.write(`event: closed\ndata: ${JSON.stringify({ reason })}\n\n`);

package/dist/server/rate-limit.d.ts

@@ -1,7 +1,12 @@
-/** Per-key token-bucket rate limiter for inbound /v1/* requests, bounding api-key-id enumeration. Dependency-free; the injectable `now` makes it
+/**
+ * Per-key token-bucket rate limiter for inbound /v1/* requests, bounding api-key-id enumeration. Dependency-free; the
+ * injectable `now` makes it
  * unit-testable. */
 export interface RateLimiter {
-    /** Consume one token for `key`: true if allowed, false if the bucket is exhausted; `now` (epoch ms) is injectable for deterministic tests. */
+    /**
+     * Consume one token for `key`: true if allowed, false if the bucket is exhausted; `now` (epoch ms) is injectable for
+     * deterministic tests.
+     */
     check(key: string, now?: number): boolean;
     readonly retryAfterSec: number;
 }
@@ -12,10 +17,17 @@ export interface RateLimiterOpts {
     burst: number;
     /** A bucket untouched for this many ms is dropped by the throttled sweep. */
     idleEvictMs: number;
-    /** Hard cap on tracked keys; the least-recently-used key is evicted on overflow. */
+    /**
+     * Hard cap on tracked keys; at the cap the least-recently-used key is evicted only once it has refilled, else unseen
+     * keys share one overflow bucket.
+     */
     maxKeys: number;
 }
-/** Token-bucket limiter with bounded memory: a sweep (at most once per `idleEvictMs`) drops idle buckets and a `maxKeys` cap evicts the least-recently-used
- * key, so a client rotating source addresses cannot grow the map without bound. */
+/**
+ * Token-bucket limiter with bounded memory: a sweep (at most once per `idleEvictMs`) drops idle buckets and a `maxKeys`
+ * cap bounds the map,
+ * so a client rotating source addresses can neither grow it without bound nor evict its own throttled bucket to get a
+ * fresh one.
+ */
 export declare function createRateLimiter(opts: RateLimiterOpts): RateLimiter;
 //# sourceMappingURL=rate-limit.d.ts.map

package/dist/server/rate-limit.js

@@ -1,10 +1,38 @@
-/** Per-key token-bucket rate limiter for inbound /v1/* requests, bounding api-key-id enumeration. Dependency-free; the injectable `now` makes it
+/**
+ * Per-key token-bucket rate limiter for inbound /v1/* requests, bounding api-key-id enumeration. Dependency-free; the
+ * injectable `now` makes it
  * unit-testable. */
-/** Token-bucket limiter with bounded memory: a sweep (at most once per `idleEvictMs`) drops idle buckets and a `maxKeys` cap evicts the least-recently-used
- * key, so a client rotating source addresses cannot grow the map without bound. */
+/** The tokens `b` holds at `now`; a clock stepped back refills nothing. */
+function tokensAt(b, now, ratePerSec, burst) {
+    return Math.min(burst, b.tokens + (Math.max(0, now - b.last) / 1000) * ratePerSec);
+}
+/**
+ * Brings `b` up to `now` and returns it; keeping the later time stops a clock that stepped back and forward again
+ * refilling that span twice.
+ */
+function refill(b, now, ratePerSec, burst) {
+    b.tokens = tokensAt(b, now, ratePerSec, burst);
+    b.last = Math.max(b.last, now);
+    return b;
+}
+function spend(b) {
+    const allowed = b.tokens >= 1;
+    if (allowed)
+        b.tokens -= 1;
+    return allowed;
+}
+/**
+ * Token-bucket limiter with bounded memory: a sweep (at most once per `idleEvictMs`) drops idle buckets and a `maxKeys`
+ * cap bounds the map,
+ * so a client rotating source addresses can neither grow it without bound nor evict its own throttled bucket to get a
+ * fresh one.
+ */
 export function createRateLimiter(opts) {
     const { ratePerSec, burst, idleEvictMs, maxKeys } = opts;
+    // SHORTCUT: one process, buckets reset on restart; a shared store table if the server runs as several processes.
     const buckets = new Map();
+    // Unseen keys draw from this while the map is full of buckets still below burst, so key churn buys no fresh bucket.
+    const overflow = { tokens: burst, last: 0 };
     let lastSweep = 0;
     function sweep(now) {
         if (now - lastSweep < idleEvictMs)
@@ -15,36 +43,37 @@ export function createRateLimiter(opts) {
                 buckets.delete(key);
         }
     }
+    /**
+     * Frees one slot for an unseen key; false when the least-recently-used bucket is still below burst, since dropping it
+     * would reset a throttled caller.
+     */
+    function makeRoom(now) {
+        if (buckets.size < maxKeys)
+            return true;
+        const lru = buckets.entries().next().value;
+        if (lru === undefined)
+            return true;
+        if (tokensAt(lru[1], now, ratePerSec, burst) < burst)
+            return false;
+        buckets.delete(lru[0]);
+        return true;
+    }
     return {
         check(key, now = Date.now()) {
             sweep(now);
             const existing = buckets.get(key);
-            let bucket;
-            if (existing === undefined) {
-                // Unseen key: a full bucket, so a fresh client's first request passes.
-                bucket = { tokens: burst, last: now };
-            }
-            else {
-                // A clock stepped back refills nothing, and keeping the later time stops the step forward again refilling that span twice.
-                const refill = (Math.max(0, now - existing.last) / 1000) * ratePerSec;
-                existing.tokens = Math.min(burst, existing.tokens + refill);
-                existing.last = Math.max(existing.last, now);
-                bucket = existing;
-                // Drop the old slot so the re-insert below puts the key last in Map
-                // iteration order — Map order then tracks least-recently-used.
+            if (existing !== undefined) {
+                // Re-inserting puts the key last in Map iteration order, so Map order tracks least-recently-used.
                 buckets.delete(key);
+                buckets.set(key, existing);
+                return spend(refill(existing, now, ratePerSec, burst));
             }
-            const allowed = bucket.tokens >= 1;
-            if (allowed)
-                bucket.tokens -= 1;
-            // Hard cap: evict the LRU key (first in iteration order) before inserting.
-            if (buckets.size >= maxKeys) {
-                const lru = buckets.keys().next().value;
-                if (lru !== undefined)
-                    buckets.delete(lru);
-            }
+            if (!makeRoom(now))
+                return spend(refill(overflow, now, ratePerSec, burst));
+            // Unseen key: a full bucket, so a fresh client's first request passes.
+            const bucket = { tokens: burst, last: now };
             buckets.set(key, bucket);
-            return allowed;
+            return spend(bucket);
         },
         // A refused bucket holds under one token and refills at ratePerSec, so one token is back within this.
         retryAfterSec: Math.max(1, Math.ceil(1 / ratePerSec)),

package/dist/server/ready.js

@@ -1,15 +1,18 @@
-import { SERVER_DB_WAIT_MS, runWithRequestStores } from '../db/index.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
-// A prober must never see a 429, so the store read is bounded by remembering its answer instead of rate-limiting the route.
+// A prober must never see a 429, so the store read is bounded by remembering its answer instead of rate-limiting the
+// route.
 const READY_WINDOW_MS = 1000;
-/** True when the store answered; one read per window whatever the caller count, and a failed read is remembered for the same window. */
+/**
+ * True when the store answered; one read per window whatever the caller count, and a failed read is remembered for the
+ * same window.
+ */
 function createReadyProbe(readiness, now = Date.now) {
     let answer;
     let inFlight;
     async function read() {
         let ok = true;
         try {
-            await runWithRequestStores(() => readiness.ping(), { busyWaitMs: SERVER_DB_WAIT_MS });
+            await readiness.ping();
         }
         catch (err) {
             log.warn(`GET /ready: the store did not answer: ${errorMessage(err)}`, errorFields(err));

package/dist/server/request.d.ts

@@ -1,5 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-/** One line per failed request; 4xx is the caller's mistake, a busy 503 is back-pressure and a 501 is a route not on this store, so none logs as an error. */
+/**
+ * One line per failed request; 4xx is the caller's mistake, a busy 503 is back-pressure and a 501 is a route not on
+ * this store, so none logs as an error.
+ */
 export declare function logRequestFailure<E>(req: IncomingMessage, err: E, status: number): void;
 /** The status and client message for a failed request; a held write lock is a retryable 503, never a 500. */
 export declare function replyFor<E>(err: E): {
@@ -11,11 +14,17 @@ interface AccessNote {
     route?: string;
     tenant?: string;
 }
-/** Names the matched route (the table's pattern, never the path sent) or the caller's tenant for the request's access line. */
+/**
+ * Names the matched route (the table's pattern, never the path sent) or the caller's tenant for the request's access
+ * line.
+ */
 export declare function noteAccess(req: IncomingMessage, note: AccessNote): void;
 /** The route name the request's access line carries, for a line about the same request logged after its reply. */
 export declare function accessRouteOf(req: IncomingMessage): string;
-/** The request's id, after stamping the headers every reply carries and starting the slow-request watchdog and the access line. */
+/**
+ * The request's id, after stamping the headers every reply carries and starting the slow-request watchdog and the
+ * access line.
+ */
 export declare function openRequest(req: IncomingMessage, res: ServerResponse, slowWarnMs?: number): string;
 export declare function sendError(res: ServerResponse, status: number, message: string): void;
 interface ParsedRoute {
@@ -25,7 +34,9 @@ interface ParsedRoute {
 }
 export declare function parseRequest(req: IncomingMessage): ParsedRoute;
 export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
-/** Rejects URL-encoded slashes in path segments BEFORE the URL parser decodes them (`%2F` would become `/` and 404 or match the wrong template).
+/**
+ * Rejects URL-encoded slashes in path segments BEFORE the URL parser decodes them (`%2F` would become `/` and 404 or
+ * match the wrong template).
  * Only the PATHNAME is scanned, so recall queries like `?q=https%3A%2F%2Fexample.com` are not rejected. */
 export declare function rejectEncodedSlash(rawUrl: string): void;
 export {};