hippo-memory 2.0.0 → 2.1.0

package/dist/util/env.js

@@ -1,5 +1,6 @@
 // The one module in src/ that reads process.env; scripts/check-env-reads.mjs fails CI on any other read.
-// Accessors read at call time, so a test that sets a variable between cases, or a HIPPO_HOME switch mid-process, still holds.
+// Accessors read at call time, so a test that sets a variable between cases, or a HIPPO_HOME switch mid-process, still
+// holds.
 function raw(name) {
     return process.env[name];
 }
@@ -24,7 +25,10 @@ function nonNegativeInt(name) {
 function trimmed(name) {
     return raw(name)?.trim() || undefined;
 }
-/** The whole environment, for code that takes it as an injectable map (agent-memory machines, owner checks, support bundles). */
+/**
+ * The whole environment, for code that takes it as an injectable map (agent-memory machines, owner checks, support
+ * bundles).
+ */
 export function processEnv() {
     return process.env;
 }
@@ -93,13 +97,18 @@ export function envLogLevel() { return raw('HIPPO_LOG')?.trim().toLowerCase() ??
 export function envLogJson() { return raw('HIPPO_LOG_FORMAT')?.trim().toLowerCase() === 'json'; }
 // Server.
 export function envPort() { return raw('HIPPO_PORT'); }
-/** How long a client waits for a running server's /health before writing to the store directly; server-detect.ts holds the default. */
+/**
+ * How long a client waits for a running server's /health before writing to the store directly; server-detect.ts holds
+ * the default.
+ */
 export function envHealthProbeMs() { return positiveInt('HIPPO_HEALTH_PROBE_MS'); }
 export function envRequireAuth() { return isOne('HIPPO_REQUIRE_AUTH'); }
 /** `1` lets a request made on this machine in with no key; HIPPO_REQUIRE_AUTH=1 wins over it. */
 export function envAllowKeylessLocal() { return isOne('HIPPO_ALLOW_KEYLESS_LOCAL'); }
 /** The role a keyless local request gets: `admin` (host admin) only when asked for by name, else `member`. */
-export function envKeylessLocalRole() { return trimmed('HIPPO_KEYLESS_LOCAL_ROLE')?.toLowerCase() === 'admin' ? 'admin' : 'member'; }
+export function envKeylessLocalRole() {
+    return trimmed('HIPPO_KEYLESS_LOCAL_ROLE')?.toLowerCase() === 'admin' ? 'admin' : 'member';
+}
 /** `1` lets a non-loopback bind start without TLS, for TLS that ends at a proxy in front. */
 export function envAllowCleartext() { return isOne('HIPPO_ALLOW_CLEARTEXT'); }
 export function envV1Rps() { return raw('HIPPO_V1_RPS'); }
@@ -112,7 +121,10 @@ export function envSleepTimeoutMs() { return positiveInt('HIPPO_SLEEP_TIMEOUT_MS
 /** How long a /v1 or /mcp request may run before the server answers 504, and a stdio MCP
  * request before its timeout error; 0 for no deadline; util/request-scope.ts holds the default. */
 export function envRequestDeadlineMs() { return nonNegativeInt('HIPPO_REQUEST_DEADLINE_MS'); }
-/** How many store calls may wait for one worker thread before the next is refused; store/sqlite/executor.ts holds the default. */
+/**
+ * How many store calls may wait for one worker thread before the next is refused; store/sqlite/executor.ts holds the
+ * default.
+ */
 export function envStoreQueueMax() { return positiveInt('HIPPO_STORE_QUEUE_MAX'); }
 /** How long the daily runner lets one child `hippo` step run; cli/setup.ts holds the default. */
 export function envDailyStepTimeoutMs() { return positiveInt('HIPPO_DAILY_STEP_TIMEOUT_MS'); }
@@ -132,25 +144,66 @@ export function envLlmTimeoutMs() { return positiveInt('HIPPO_LLM_TIMEOUT_MS');
 export function envTypesafeApiKey() { return trimmed('TYPESAFE_API_KEY'); }
 export function envJevTimeoutMs() { return positiveInt('HIPPO_JEV_TIMEOUT_MS'); }
 export function envJevModel() { return raw('HIPPO_JEV_MODEL'); }
-/** How long a recall waits for an API provider to embed its query before ranking on BM25 alone; search/vector.ts holds the default. */
-export function envQueryEmbedTimeoutMs() { return positiveInt('HIPPO_QUERY_EMBED_TIMEOUT_MS'); }
-export function envLlmRerankerUrl() { return raw('HIPPO_LLM_RERANKER_URL'); }
-export function envLlmRerankerKey() { return raw('HIPPO_LLM_RERANKER_KEY'); }
-export function envLlmRerankerModel() { return raw('HIPPO_LLM_RERANKER_MODEL'); }
-export function envLlmRerankerTimeoutMs() { return positiveInt('HIPPO_LLM_RERANKER_TIMEOUT_MS'); }
-export function envClefEndpoint() { return raw('HIPPO_CLEF_ENDPOINT')?.trim(); }
-export function envClefEndpointToken() { return raw('HIPPO_CLEF_ENDPOINT_TOKEN')?.trim() || undefined; }
-export function envClefTimeoutMs() { return raw('HIPPO_CLEF_TIMEOUT_MS'); }
-export function envCloudflareAccountId() { return raw('CLOUDFLARE_ACCOUNT_ID')?.trim() ?? ''; }
-export function envCloudflareApiToken() { return raw('CLOUDFLARE_API_TOKEN')?.trim() ?? ''; }
+/**
+ * How long a recall waits for an API provider to embed its query before ranking on BM25 alone; search/vector.ts holds
+ * the default.
+ */
+export function envQueryEmbedTimeoutMs() {
+    return positiveInt('HIPPO_QUERY_EMBED_TIMEOUT_MS');
+}
+export function envLlmRerankerUrl() {
+    return raw('HIPPO_LLM_RERANKER_URL');
+}
+export function envLlmRerankerKey() {
+    return raw('HIPPO_LLM_RERANKER_KEY');
+}
+export function envLlmRerankerModel() {
+    return raw('HIPPO_LLM_RERANKER_MODEL');
+}
+export function envLlmRerankerTimeoutMs() {
+    return positiveInt('HIPPO_LLM_RERANKER_TIMEOUT_MS');
+}
+export function envClefEndpoint() {
+    return raw('HIPPO_CLEF_ENDPOINT')?.trim();
+}
+export function envClefEndpointToken() {
+    return raw('HIPPO_CLEF_ENDPOINT_TOKEN')?.trim() || undefined;
+}
+export function envClefTimeoutMs() {
+    return raw('HIPPO_CLEF_TIMEOUT_MS');
+}
+export function envCloudflareAccountId() {
+    return raw('CLOUDFLARE_ACCOUNT_ID')?.trim() ?? '';
+}
+export function envCloudflareApiToken() {
+    return raw('CLOUDFLARE_API_TOKEN')?.trim() ?? '';
+}
 // Connectors.
-export function envSlackBotToken() { return raw('SLACK_BOT_TOKEN'); }
-export function envSlackTeamId() { return raw('SLACK_TEAM_ID'); }
-export function envSlackSigningSecret() { return raw('SLACK_SIGNING_SECRET'); }
-export function envSlackSigningSecretPrevious() { return raw('SLACK_SIGNING_SECRET_PREVIOUS'); }
-export function envSlackAllowUnknownTeamFallback() { return isOne('SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK'); }
-export function envGitHubToken() { return raw('GITHUB_TOKEN'); }
-export function envGitHubWebhookSecret() { return raw('GITHUB_WEBHOOK_SECRET'); }
-export function envGitHubWebhookSecretPrevious() { return raw('GITHUB_WEBHOOK_SECRET_PREVIOUS'); }
-export function envGitHubAllowUnknownInstallationFallback() { return isOne('GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK'); }
+export function envSlackBotToken() {
+    return raw('SLACK_BOT_TOKEN');
+}
+export function envSlackTeamId() {
+    return raw('SLACK_TEAM_ID');
+}
+export function envSlackSigningSecret() {
+    return raw('SLACK_SIGNING_SECRET');
+}
+export function envSlackSigningSecretPrevious() {
+    return raw('SLACK_SIGNING_SECRET_PREVIOUS');
+}
+export function envSlackAllowUnknownTeamFallback() {
+    return isOne('SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK');
+}
+export function envGitHubToken() {
+    return raw('GITHUB_TOKEN');
+}
+export function envGitHubWebhookSecret() {
+    return raw('GITHUB_WEBHOOK_SECRET');
+}
+export function envGitHubWebhookSecretPrevious() {
+    return raw('GITHUB_WEBHOOK_SECRET_PREVIOUS');
+}
+export function envGitHubAllowUnknownInstallationFallback() {
+    return isOne('GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK');
+}
 //# sourceMappingURL=env.js.map

package/dist/util/home-path.js

@@ -1,11 +1,14 @@
-// Home-directory paths name their user, so text bound for a shared store tests or masks them here; no imports keep it light.
+// Home-directory paths name their user, so text bound for a shared
+// store tests or masks them here; no imports keep it light.
 // VS Code writes file links URL-encoded, so a separator may be %5C or %2F.
 const WIN_SEP = String.raw `(?:[\\/]|%5[Cc]|%2[Ff])`;
 const WIN_CHAR = String.raw `(?:(?!%5[Cc]|%2[Ff])[^\\/:*?"<>|\s])`;
 // A Windows name never holds a quote, so JSON stops it; one with spaces runs to a separator, quote,
 // closing mark or line end, leaving the mark, as stopping at its first word leaks the surname.
-const WIN_USER = String.raw `(?:${WIN_CHAR}+(?: ${WIN_CHAR}+){0,3}(?=${WIN_SEP}|["'\`)\]>,;]|\.(?=\s|$)|(?<!\.)(?:[^\S ]|$))(?<![\`)\],;'])|${WIN_CHAR}+)`;
-// Slash-led homes with their case spelled out and no flag, so one pattern can hold all four: Git Bash and WSL mounts, Linux, root and macOS.
+const WIN_USER = String.raw `(?:${WIN_CHAR}+(?: ${WIN_CHAR}+){0,3}(?=${WIN_SEP}|["'\`)\]>,;]|\.(?=\s|$)|` +
+    String.raw `(?<!\.)(?:[^\S ]|$))(?<![\`)\],;'])|${WIN_CHAR}+)`;
+// Slash-led homes with their case spelled out and no flag, so one pattern can hold all four: Git Bash and WSL mounts,
+// Linux, root and macOS.
 const MOUNT_HOME = String.raw `(?:\/[Mm][Nn][Tt])?\/[A-Za-z]\/[Uu][Ss][Ee][Rr][Ss]\/${WIN_USER}`;
 const LINUX_HOME = String.raw `(?:\/var)?\/home\/[^/\s]+`;
 const ROOT_HOME = String.raw `(?:\/var)?\/root(?![\w.-])`;
@@ -35,8 +38,10 @@ const MASK = '[home]';
 // Global copies, so the shared test patterns keep their lastIndex at 0.
 const allOf = (re) => new RegExp(re.source, `${re.flags}g`);
 const [DRIVE_HOMES, LONG_PATHS, SHARE_HOMES, SHORT_NAMES] = [DRIVE_HOME, LONG_PATH, SHARE_HOME, SHORT_NAME].map(allOf);
-// A home glued after another starts where a mask will end, which no guard refuses: one match takes the whole run, as masking one a pass costs a pass per home.
-// A run holds only shapes whose own step is not still to come, so a later step meets the same text it would without the run.
+// A home glued after another starts where a mask will end, which no guard
+// refuses: one match takes the whole run, as masking one a pass costs a
+// pass per home. A run holds only shapes whose own step is not still to
+// come, so a later step meets the same text it would without the run.
 const runFrom = (start, ...glued) => new RegExp(`${start}(?:${glued.join('|')})*`, 'g');
 const MOUNT_RUNS = runFrom(MOUNT_START, MOUNT_HOME);
 const LINUX_RUNS = runFrom(LINUX_START, MOUNT_HOME, LINUX_HOME);
@@ -59,7 +64,8 @@ function maskOnce(text) {
 export function maskHomePaths(text) {
     let out = text;
     let next = maskOnce(out);
-    // A mask can uncover a home path its text was hiding, so passes repeat until one changes nothing; each takes a separator out, so they end.
+    // A mask can uncover a home path its text was hiding, so passes repeat until one changes nothing; each takes a
+    // separator out, so they end.
     while (next !== out) {
         out = next;
         next = maskOnce(out);

package/dist/util/hook-payload.d.ts

@@ -2,7 +2,9 @@
 export declare function hookPayloadSessionId(stdinText: string | undefined, requiredSource?: string | null): string | null;
 /** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
 export declare function hookPayloadString(stdinText: string | undefined, field: string): string | null;
-/** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
+/**
+ * Whether a hook fired inside a sub-agent, the only payload with `agent_id`
+ * (https://code.claude.com/docs/en/hooks#common-input-fields).
  *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
 export declare function isSubagentPayload(stdinText: string | undefined): boolean;
 //# sourceMappingURL=hook-payload.d.ts.map

package/dist/util/hook-payload.js

@@ -28,7 +28,9 @@ export function hookPayloadString(stdinText, field) {
     const value = parseHookPayload(stdinText)?.[field];
     return isJsonString(value) ? value : null;
 }
-/** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
+/**
+ * Whether a hook fired inside a sub-agent, the only payload with `agent_id`
+ * (https://code.claude.com/docs/en/hooks#common-input-fields).
  *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
 export function isSubagentPayload(stdinText) {
     const agentId = parseHookPayload(stdinText)?.agent_id;

package/dist/util/http-retry.d.ts

@@ -1,17 +1,20 @@
-/** One retry policy for outbound HTTP: a timeout on every attempt, backoff on 429 and 5xx, and on a dropped connection where a replay is safe. */
+/** One retry policy for outbound HTTP: a timeout on every attempt, backoff on 429 and 5xx, and on a dropped
+ * connection where a replay is safe. */
 export interface RetryPolicy {
     /** Per-attempt limit; a stalled peer ends as a thrown `TimeoutError`, never a hang. */
     timeoutMs: number;
     /** Total attempts including the first. */
     attempts?: number;
-    /** Limit on the whole call, waits included: an attempt is cut short at it and no retry starts whose wait would reach it. */
+    /** Limit on the whole call, waits included: an attempt is cut short at it and no retry starts whose wait would
+     * reach it. */
     totalMs?: number;
     baseDelayMs?: number;
     /** A Retry-After longer than this hands the response back, so a caller with its own long pause keeps it. */
     maxDelayMs?: number;
     /** Which responses to retry; defaults to 429 and 5xx. A write narrows it to answers that prove nothing committed. */
     retryOn?: (res: Response) => boolean;
-    /** Also retry a dropped connection or a timed-out attempt. On for GET and HEAD; any other method turns it on only when a replay cannot commit twice. */
+    /** Also retry a dropped connection or a timed-out attempt. On for GET and HEAD; any other method turns it on only
+     * when a replay cannot commit twice. */
     retryTransport?: boolean;
     fetchFn?: typeof fetch;
     /** Replaces the timer between attempts. A caller `signal` that aborts still ends the wait at once. */
@@ -20,14 +23,17 @@ export interface RetryPolicy {
     /** Replaces the clock `totalMs` is measured on. */
     now?: () => number;
 }
-/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
+/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS`
+ * overrides it. */
 export declare function llmTimeoutMs(): number;
-/** One LLM call with its retries: two full attempts and the longest wait between them, where three slow failures would hold a sleep for 3x the timeout. */
+/** One LLM call with its retries: two full attempts and the longest wait between them, where three slow failures
+ * would hold a sleep for 3x the timeout. */
 export declare function llmTotalMs(): number;
 export declare function isRetryableStatus(status: number): boolean;
 /** Retry-After as milliseconds: delta-seconds or an HTTP date; null when absent or unreadable. */
 export declare function parseRetryAfterMs(header: string | null, now?: number): number | null;
-/** A dropped connection, a DNS hiccup or a timed-out attempt: faults a second try can clear. A refused connection is not one. */
+/** A dropped connection, a DNS hiccup or a timed-out attempt: faults a second try can clear. A refused connection is
+ * not one. */
 export declare function isTransientTransportError<E>(err: E): boolean;
 /** `fetch` with a per-attempt timeout and up to `attempts` tries on 429, 5xx and (see
  * `retryTransport`) transport faults; the last response or error comes back as is. */

package/dist/util/http-retry.js

@@ -1,4 +1,5 @@
-/** One retry policy for outbound HTTP: a timeout on every attempt, backoff on 429 and 5xx, and on a dropped connection where a replay is safe. */
+/** One retry policy for outbound HTTP: a timeout on every attempt, backoff on 429 and 5xx, and on a dropped
+ * connection where a replay is safe. */
 import { MINUTE_MS } from './time.js';
 import { envLlmTimeoutMs } from './env.js';
 import { errorCode, errorFields, log } from './log.js';
@@ -6,11 +7,13 @@ const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_BASE_DELAY_MS = 250;
 const DEFAULT_MAX_DELAY_MS = 8_000;
 const DEFAULT_LLM_TIMEOUT_MS = MINUTE_MS;
-/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
+/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS`
+ * overrides it. */
 export function llmTimeoutMs() {
     return envLlmTimeoutMs() ?? DEFAULT_LLM_TIMEOUT_MS;
 }
-/** One LLM call with its retries: two full attempts and the longest wait between them, where three slow failures would hold a sleep for 3x the timeout. */
+/** One LLM call with its retries: two full attempts and the longest wait between them, where three slow failures
+ * would hold a sleep for 3x the timeout. */
 export function llmTotalMs() {
     return 2 * llmTimeoutMs() + DEFAULT_MAX_DELAY_MS;
 }
@@ -31,7 +34,8 @@ export function parseRetryAfterMs(header, now = Date.now()) {
 const TRANSIENT_CODES = new Set([
     'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT',
 ]);
-/** A dropped connection, a DNS hiccup or a timed-out attempt: faults a second try can clear. A refused connection is not one. */
+/** A dropped connection, a DNS hiccup or a timed-out attempt: faults a second try can clear. A refused connection is
+ * not one. */
 export function isTransientTransportError(err) {
     if (!(err instanceof Error))
         return false;
@@ -58,7 +62,11 @@ function redactedTarget(url) {
 function logRetry(init, url, reason, attempt, attempts, delayMs) {
     // Debug: an attempt that may still succeed is not a warning, and the caller reports the final failure.
     log.debug('http retry', {
-        method: (init.method ?? 'GET').toUpperCase(), target: redactedTarget(url), reason, attempt: `${attempt}/${attempts}`, delayMs: Math.round(delayMs),
+        method: (init.method ?? 'GET').toUpperCase(),
+        target: redactedTarget(url),
+        reason,
+        attempt: `${attempt}/${attempts}`,
+        delayMs: Math.round(delayMs),
     });
 }
 // `cancel` clears the timer, so a wait the caller left does not keep the process alive.
@@ -66,7 +74,8 @@ const timerSleep = (ms, cancel) => new Promise((resolve) => {
     const timer = setTimeout(resolve, ms);
     cancel?.addEventListener('abort', () => clearTimeout(timer), { once: true });
 });
-/** The wait between attempts. With a caller signal it ends the moment that signal aborts and rejects with its reason, so no further attempt starts. */
+/** The wait between attempts. With a caller signal it ends the moment that signal aborts and rejects with its
+ * reason, so no further attempt starts. */
 async function backoffWait(ms, sleep, signal) {
     if (!signal)
         return (sleep ?? timerSleep)(ms);
@@ -132,6 +141,7 @@ export async function fetchWithRetry(url, init, policy) {
             await res.body?.cancel();
         }
         catch (err) {
+            // Best-effort: the response is spent either way, so a failed cancel only leaves the socket to idle out.
             log.debug('http retry: body cancel failed', errorFields(err));
         }
         logRetry(init, url, `status ${res.status}`, attempt, attempts, delay);

package/dist/util/http-util.d.ts

@@ -10,7 +10,10 @@ export declare class HttpError extends Error {
     readonly retryAfterSec: number | undefined;
     constructor(status: number, message: string, retryAfterSec?: number);
 }
-/** A request, or a store call it waited on, ran past the request's deadline; the reply carries `code` so a client branches without parsing prose. */
+/**
+ * A request, or a store call it waited on, ran past the request's deadline; the reply carries `code` so a client
+ * branches without parsing prose.
+ */
 export declare class DeadlineExceededError extends HttpError {
     readonly code = "deadline_exceeded";
     constructor(message: string);
@@ -25,7 +28,10 @@ export declare const INTERNAL_ERROR_MESSAGE = "internal server error";
 export declare const STORE_NOT_PORTED_MESSAGE = "store_not_ported";
 /** Serialises before the head goes out, so a body that is not JSON still reaches the caller's error reply. */
 export declare function sendJson<T>(res: ServerResponse, status: number, body: T): void;
-/** How long any route waits for a request body, so a client that sends headers and then stalls cannot hold a request open: 30 s, or HIPPO_BODY_TIMEOUT_MS. */
+/**
+ * How long any route waits for a request body, so a client that sends headers and then stalls cannot hold a request
+ * open: 30 s, or HIPPO_BODY_TIMEOUT_MS.
+ */
 export declare function bodyDeadlineMs(): number;
 export interface ReadBodyOpts {
     /** Defaults to 1 MB. */
@@ -33,7 +39,10 @@ export interface ReadBodyOpts {
     /** Fails with BodyTimeoutError when the whole body has not arrived by then; defaults to bodyDeadlineMs(). */
     deadlineMs?: number;
 }
-/** The body as text, refused mid-stream past maxBytes and past deadlineMs, so an oversized or slow sender cannot tie up the server. */
+/**
+ * The body as text, refused mid-stream past maxBytes and past deadlineMs, so an oversized or slow sender cannot tie up
+ * the server.
+ */
 export declare function readBody(req: IncomingMessage, { maxBytes, deadlineMs }?: ReadBodyOpts): Promise<string>;
 export declare function closeAfterReply(req: IncomingMessage): void;
 export declare const LOOPBACK_HOST_HEADER: RegExp;
@@ -48,8 +57,14 @@ export interface WebhookRequest {
         webhookBodyDeadlineMs?: number;
     };
 }
-/** Call before refusing a webhook unread: a caller still sending its body loses the socket once the reply is out, as it does after a 413. */
+/**
+ * Call before refusing a webhook unread: a caller still sending its body loses the socket once the reply is out, as it
+ * does after a 413.
+ */
 export declare function closeIfBodyUnread({ req, res }: WebhookRequest): void;
-/** A webhook's raw body, exactly as sent, for the receiver's HMAC check; call it only once a secret is configured and the signature headers are present. */
+/**
+ * A webhook's raw body, exactly as sent, for the receiver's HMAC check; call it only once a secret is configured and
+ * the signature headers are present.
+ */
 export declare function readWebhookBody({ req, opts }: WebhookRequest): Promise<string>;
 //# sourceMappingURL=http-util.d.ts.map

package/dist/util/http-util.js

@@ -11,7 +11,8 @@ export const MAX_BODY_BYTES = 1024 * 1024;
 function sizeLabel(bytes) {
     return bytes % (1024 * 1024) === 0 ? `${bytes / (1024 * 1024)}MB` : `${Math.ceil(bytes / 1024)}KB`;
 }
-// How long a refused upload is still read and discarded after its reply, so a client that never stops cannot hold the socket.
+// How long a refused upload is still read and discarded after its reply, so a client that never stops cannot hold the
+// socket.
 const REFUSED_UPLOAD_LINGER_MS = 2000;
 export const JSON_HEADERS = { 'content-type': 'application/json' };
 export class HttpError extends Error {
@@ -24,7 +25,10 @@ export class HttpError extends Error {
         this.retryAfterSec = retryAfterSec;
     }
 }
-/** A request, or a store call it waited on, ran past the request's deadline; the reply carries `code` so a client branches without parsing prose. */
+/**
+ * A request, or a store call it waited on, ran past the request's deadline; the reply carries `code` so a client
+ * branches without parsing prose.
+ */
 export class DeadlineExceededError extends HttpError {
     code = 'deadline_exceeded';
     constructor(message) {
@@ -48,11 +52,17 @@ export function sendJson(res, status, body) {
     res.end(text);
 }
 const DEFAULT_BODY_DEADLINE_MS = 30_000;
-/** How long any route waits for a request body, so a client that sends headers and then stalls cannot hold a request open: 30 s, or HIPPO_BODY_TIMEOUT_MS. */
+/**
+ * How long any route waits for a request body, so a client that sends headers and then stalls cannot hold a request
+ * open: 30 s, or HIPPO_BODY_TIMEOUT_MS.
+ */
 export function bodyDeadlineMs() {
     return envBodyTimeoutMs() ?? DEFAULT_BODY_DEADLINE_MS;
 }
-/** The body as text, refused mid-stream past maxBytes and past deadlineMs, so an oversized or slow sender cannot tie up the server. */
+/**
+ * The body as text, refused mid-stream past maxBytes and past deadlineMs, so an oversized or slow sender cannot tie up
+ * the server.
+ */
 export function readBody(req, { maxBytes = MAX_BODY_BYTES, deadlineMs = bodyDeadlineMs() } = {}) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -63,7 +73,8 @@ export function readBody(req, { maxBytes = MAX_BODY_BYTES, deadlineMs = bodyDead
             chunks.length = 0;
             reject(err);
         };
-        // Not for-await: leaving that loop early destroys the request, so the socket stops reading and the 413 caller cannot close it cleanly.
+        // Not for-await: leaving that loop early destroys the request, so the socket stops reading and the 413 caller
+        // cannot close it cleanly.
         const onData = (chunk) => {
             total += chunk.length;
             if (total <= maxBytes) {
@@ -84,7 +95,8 @@ export function readBody(req, { maxBytes = MAX_BODY_BYTES, deadlineMs = bodyDead
         });
     });
 }
-// A full close with request bytes unread sends a TCP reset, which discards the reply before the client reads it (RFC 9112 9.6).
+// A full close with request bytes unread sends a TCP reset, which discards the reply before the client reads it (RFC
+// 9112 9.6).
 export function closeAfterReply(req) {
     const socket = req.socket;
     req.resume();
@@ -112,16 +124,23 @@ function originHost(origin) {
         return null;
     }
 }
-// A webhook route takes no key, so anyone holding a signature header could otherwise keep a socket open with a body that never ends.
+// A webhook route takes no key, so anyone holding a signature header could otherwise keep a socket open with a body
+// that never ends.
 const WEBHOOK_BODY_DEADLINE_MS = 10_000;
-/** Call before refusing a webhook unread: a caller still sending its body loses the socket once the reply is out, as it does after a 413. */
+/**
+ * Call before refusing a webhook unread: a caller still sending its body loses the socket once the reply is out, as it
+ * does after a 413.
+ */
 export function closeIfBodyUnread({ req, res }) {
     res.once('finish', () => {
         if (!req.complete)
             closeAfterReply(req);
     });
 }
-/** A webhook's raw body, exactly as sent, for the receiver's HMAC check; call it only once a secret is configured and the signature headers are present. */
+/**
+ * A webhook's raw body, exactly as sent, for the receiver's HMAC check; call it only once a secret is configured and
+ * the signature headers are present.
+ */
 export function readWebhookBody({ req, opts }) {
     return readBody(req, { deadlineMs: opts.webhookBodyDeadlineMs ?? WEBHOOK_BODY_DEADLINE_MS });
 }

package/dist/util/json.d.ts

@@ -12,6 +12,9 @@ export declare function isJsonObject(value: JsonValue | undefined): value is {
 export declare function isJsonObjectLiteral(value: JsonValue | undefined): value is {
     [key: string]: JsonValue;
 };
-/** Windows PowerShell 5.1 saves JSON with a UTF-8 byte order mark that JSON.parse rejects, so one leading mark is dropped. */
+/**
+ * Windows PowerShell 5.1 saves JSON with a UTF-8 byte order mark that JSON.parse rejects, so one leading mark is
+ * dropped.
+ */
 export declare function readJsonFile(file: string): JsonValue;
 //# sourceMappingURL=json.d.ts.map

package/dist/util/json.js

@@ -17,7 +17,10 @@ export function isJsonObject(value) {
 export function isJsonObjectLiteral(value) {
     return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;
 }
-/** Windows PowerShell 5.1 saves JSON with a UTF-8 byte order mark that JSON.parse rejects, so one leading mark is dropped. */
+/**
+ * Windows PowerShell 5.1 saves JSON with a UTF-8 byte order mark that JSON.parse rejects, so one leading mark is
+ * dropped.
+ */
 export function readJsonFile(file) {
     const text = fs.readFileSync(file, 'utf8');
     return JSON.parse(text.codePointAt(0) === 0xfeff ? text.slice(1) : text);

package/dist/util/keyset.js

@@ -1,4 +1,5 @@
-// Keyset paging for list queries ordered by (sort key DESC, id DESC), so a page never skips or repeats a row when rows arrive between requests.
+// Keyset paging for list queries ordered by (sort key DESC, id DESC), so a page never skips or repeats a row when rows
+// arrive between requests.
 /** An ` AND ...` WHERE fragment and its params selecting rows strictly after `after`; empty when `after` is unset. */
 export function keysetAfter(sortCol, idCol, after) {
     if (!after)

package/dist/util/limits.js

@@ -1,8 +1,10 @@
-// Cap for id-shaped request fields (ids, tenant, session, scope, class): far above real values, small enough to bound logs and indexes.
+// Cap for id-shaped request fields (ids, tenant, session, scope, class): far above real values, small enough to bound
+// logs and indexes.
 export const MAX_ID_LEN = 256;
 // Page size every list surface (CLI, HTTP, store) falls back to when the caller names none.
 export const DEFAULT_LIST_LIMIT = 100;
-// Ceiling for a caller-named list page; SQLite `LIMIT ?` and one response's size bound it, and every list surface shares it.
+// Ceiling for a caller-named list page; SQLite `LIMIT ?` and one response's size bound it, and every list surface
+// shares it.
 export const MAX_LIST_LIMIT = 1000;
 /** The one list-limit rule: absent means the default; a positive integer up to the ceiling passes.
  * Anything else returns undefined, so each surface words its own error. */

package/dist/util/log.d.ts

@@ -1,7 +1,8 @@
 /** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info,
  * debug); unset or unknown means warn. `HIPPO_LOG_FORMAT=json` writes JSON lines. */
 export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
-/** Extra key=value pairs appended to the line. `ts` and, inside a request, `requestId` are added to every line written. */
+/** Extra key=value pairs appended to the line. `ts` and, inside a request, `requestId` are added to every line
+ * written. */
 export interface LogFields {
     ts?: string;
     requestId?: string;
@@ -14,10 +15,15 @@ export declare function isLevelEnabled(level: LogLevel): boolean;
 export declare function formatLogLine(level: LogLevel, message: string, fields?: LogFields): string;
 /** One JSON object per line for a log collector; JSON escaping keeps a multi-line value on the one line. */
 export declare function formatLogJson(level: LogLevel, message: string, fields?: LogFields): string;
-/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. Past the key cap an unseen key logs at debug. */
+/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. Past the key
+ * cap an unseen key logs at debug. */
 declare function once(key: string, level: LogLevel, message: string, fields?: LogFields): void;
-/** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable without flooding stderr. */
+/** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable
+ * without flooding stderr. */
 declare function warnThenDebug(key: string, message: string, fields?: LogFields): void;
+/** Warn the first time `key` is seen, then count repeats at debug and warn again with the running count on every
+ * 100th, so a failure that keeps happening stays visible without flooding stderr. */
+declare function warnThenSample(key: string, message: string, fields?: LogFields): void;
 /** The class name and stack of a thrown value, as log fields; a non-Error throw has no stack. */
 export declare function errorFields<E>(err: E): LogFields;
 export declare const log: {
@@ -27,11 +33,13 @@ export declare const log: {
     readonly debug: (message: string, fields?: LogFields) => void;
     readonly once: typeof once;
     readonly warnThenDebug: typeof warnThenDebug;
+    readonly warnThenSample: typeof warnThenSample;
 };
-/** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause enrichment). */
+/** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause
+ * enrichment). */
 export declare function errorMessage(cause: unknown): string;
 /** One post-compact failure, told once to the hook's output (`say`) and once to the structured log. */
-export declare function reportCompactionFailure(say: (message: string) => void, step: string, reason: string): void;
+export declare function reportCompactionFailure(say: (message: string) => void, step: string, reason: string, fields?: LogFields): void;
 /** The string `code` of a caught value (an errno name such as EACCES), or '' when it has none. */
 export declare function errorCode(cause: unknown): string;
 /** Test hook: forget which once-keys have fired. */

package/dist/util/log.js

@@ -41,7 +41,8 @@ function write(level, message, fields) {
 const ONCE_KEY_CAP = 1_000;
 const onceKeys = new Set();
 let onceCapReported = false;
-/** 'new' records the key and 'seen' is a repeat. 'uncounted' is an unseen key once the set is full: it is not recorded, and the first one says so at warn. */
+/** 'new' records the key and 'seen' is a repeat. 'uncounted' is an unseen key once the set is full: it is not
+ * recorded, and the first one says so at warn. */
 function sightOnceKey(key) {
     if (onceKeys.has(key))
         return 'seen';
@@ -55,16 +56,35 @@ function sightOnceKey(key) {
     }
     return 'uncounted';
 }
-/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. Past the key cap an unseen key logs at debug. */
+/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. Past the key
+ * cap an unseen key logs at debug. */
 function once(key, level, message, fields) {
     const sighting = sightOnceKey(key);
     if (sighting !== 'seen')
         write(sighting === 'new' ? level : 'debug', message, fields);
 }
-/** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable without flooding stderr. */
+/** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable
+ * without flooding stderr. */
 function warnThenDebug(key, message, fields) {
     write(sightOnceKey(key) === 'new' ? 'warn' : 'debug', message, fields);
 }
+const SAMPLE_EVERY = 100;
+const repeatCounts = new Map();
+/** Warn the first time `key` is seen, then count repeats at debug and warn again with the running count on every
+ * 100th, so a failure that keeps happening stays visible without flooding stderr. */
+function warnThenSample(key, message, fields) {
+    if (sightOnceKey(key) === 'new') {
+        write('warn', message, fields);
+        return;
+    }
+    // Counts only keys sightOnceKey recorded, so the map is bounded by ONCE_KEY_CAP.
+    const seen = (repeatCounts.get(key) ?? 0) + 1;
+    repeatCounts.set(key, seen);
+    if (seen % SAMPLE_EVERY === 0)
+        write('warn', `${message} (${seen} more since the first warning)`, fields);
+    else
+        write('debug', message, fields);
+}
 /** The class name and stack of a thrown value, as log fields; a non-Error throw has no stack. */
 export function errorFields(err) {
     if (!(err instanceof Error))
@@ -78,15 +98,17 @@ export const log = {
     debug: (message, fields) => write('debug', message, fields),
     once,
     warnThenDebug,
+    warnThenSample,
 };
-/** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause enrichment). */
+/** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause
+ * enrichment). */
 export function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
 /** One post-compact failure, told once to the hook's output (`say`) and once to the structured log. */
-export function reportCompactionFailure(say, step, reason) {
+export function reportCompactionFailure(say, step, reason, fields) {
     say(`${step} failed: ${reason}`);
-    log.error(`post-compact: ${step} failed: ${reason}`);
+    log.error(`post-compact: ${step} failed: ${reason}`, fields);
 }
 /** The string `code` of a caught value (an errno name such as EACCES), or '' when it has none. */
 export function errorCode(cause) {
@@ -95,6 +117,7 @@ export function errorCode(cause) {
 /** Test hook: forget which once-keys have fired. */
 export function resetLogOnce() {
     onceKeys.clear();
+    repeatCounts.clear();
     onceCapReported = false;
 }
 //# sourceMappingURL=log.js.map

package/dist/util/net.d.ts

@@ -0,0 +1,5 @@
+/** A URL hostname that stays on this machine: localhost, ::1 (bracketed or not) or any 127.0.0.0/8 address. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/** A socket remote address on this machine; Node reports a dual-stack IPv4 peer as '::ffff:127.x.x.x'. */
+export declare function isLoopbackAddress(remoteAddress: string | undefined): boolean;
+//# sourceMappingURL=net.d.ts.map