hippo-memory 1.69.0 → 1.71.0

package/dist/util/home-path.js

@@ -0,0 +1,69 @@
+// 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 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.-])`;
+const MAC_HOME = String.raw `\/Users\/[^/\s]+`;
+const DRIVE_HOME = new RegExp(String.raw `[A-Za-z](?::|%3A)${WIN_SEP}+(?:Users|Documents and Settings)${WIN_SEP}+${WIN_USER}`, 'i');
+const LONG_PATH = /\\\\\?\\/;
+const SHARE_HOME = new RegExp(String.raw `\\\\[^\\/\s]+\\+(?:homes?|users|profiles?)\$?\\+${WIN_USER}`, 'i');
+const SHORT_NAME = /[\\/][A-Z0-9_$]{1,6}~\d{1,6}(?:\.[A-Z0-9]{1,3})?(?![\w~])|\b[A-Z0-9_$]{1,6}~\d{1,6}(?:\.[A-Z0-9]{1,3})?[\\/]/;
+// A slash-led home counts only at the start of a path, so each takes a guard against the text before it.
+const MOUNT_START = String.raw `(?<![\w.])${MOUNT_HOME}`;
+const LINUX_START = String.raw `(?<![\w.~-])${LINUX_HOME}`;
+const ROOT_START = String.raw `(?<![\w.~-])${ROOT_HOME}`;
+const MAC_START = String.raw `(?<![\w.~-])${MAC_HOME}`;
+/** One pattern per path shape that carries a user name: Windows, Git Bash and WSL
+ * mounts, extended-length, UNC home shares, Linux, macOS and 8.3 short names. */
+export const USER_SEGMENT = [
+    DRIVE_HOME,
+    new RegExp(MOUNT_START),
+    LONG_PATH,
+    SHARE_HOME,
+    new RegExp(LINUX_START),
+    new RegExp(ROOT_START),
+    new RegExp(MAC_START),
+    SHORT_NAME,
+];
+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.
+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);
+const ROOT_RUNS = runFrom(ROOT_START, MOUNT_HOME, LINUX_HOME, ROOT_HOME);
+const MAC_RUNS = runFrom(MAC_START, MOUNT_HOME, LINUX_HOME, ROOT_HOME, MAC_HOME);
+const SLASH_HOMES = new RegExp(`${MOUNT_HOME}|${LINUX_HOME}|${ROOT_HOME}|${MAC_HOME}`, 'g');
+const maskRun = (run) => MASK.repeat(run.match(SLASH_HOMES)?.length ?? 1);
+function maskOnce(text) {
+    return text
+        .replace(DRIVE_HOMES, MASK)
+        .replace(MOUNT_RUNS, maskRun)
+        .replace(LONG_PATHS, MASK)
+        .replace(SHARE_HOMES, MASK)
+        .replace(LINUX_RUNS, maskRun)
+        .replace(ROOT_RUNS, maskRun)
+        .replace(MAC_RUNS, maskRun)
+        .replace(SHORT_NAMES, MASK);
+}
+/** `text` with each home-directory segment replaced by `[home]`. */
+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.
+    while (next !== out) {
+        out = next;
+        next = maskOnce(out);
+    }
+    return out;
+}
+//# sourceMappingURL=home-path.js.map

package/dist/{http-retry.d.ts → util/http-retry.d.ts}

@@ -1,4 +1,4 @@
-/** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
+/** 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;
@@ -9,7 +9,10 @@ export interface RetryPolicy {
     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. */
+    retryTransport?: boolean;
     fetchFn?: typeof fetch;
+    /** Replaces the timer between attempts. A caller `signal` that aborts still ends the wait at once. */
     sleep?: (ms: number) => Promise<void>;
     random?: () => number;
 }
@@ -18,6 +21,9 @@ export declare function llmTimeoutMs(): 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;
-/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429 and 5xx; the last response comes back as is and transport errors throw at once. */
+/** 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. */
 export declare function fetchWithRetry(url: string | URL, init: RequestInit, policy: RetryPolicy): Promise<Response>;
 //# sourceMappingURL=http-retry.d.ts.map

package/dist/util/http-retry.js

@@ -0,0 +1,103 @@
+/** 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 { envLlmTimeoutMs } from './env.js';
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 250;
+const DEFAULT_MAX_DELAY_MS = 8_000;
+const DEFAULT_LLM_TIMEOUT_MS = 60_000;
+/** 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;
+}
+export function isRetryableStatus(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+/** Retry-After as milliseconds: delta-seconds or an HTTP date; null when absent or unreadable. */
+export function parseRetryAfterMs(header, now = Date.now()) {
+    if (header === null || header.trim() === '')
+        return null;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+// Node's fetch reports a broken socket as a bare `fetch failed` with one of these on its cause.
+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. */
+export function isTransientTransportError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === 'TimeoutError')
+        return true;
+    const holder = err.cause instanceof Object ? err.cause : err;
+    const code = 'code' in holder ? String(holder.code) : '';
+    return TRANSIENT_CODES.has(code) || err.message.toLowerCase().includes('socket hang up');
+}
+function isIdempotent(method) {
+    const verb = (method ?? 'GET').toUpperCase();
+    return verb === 'GET' || verb === 'HEAD';
+}
+// `cancel` clears the timer, so a wait the caller left does not keep the process alive.
+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. */
+async function backoffWait(ms, sleep, signal) {
+    if (!signal)
+        return (sleep ?? timerSleep)(ms);
+    signal.throwIfAborted();
+    const left = new AbortController();
+    const aborted = new Promise((_resolve, reject) => {
+        signal.addEventListener('abort', () => reject(signal.reason), { once: true, signal: left.signal });
+    });
+    try {
+        // An injected sleep cannot be cancelled, so it is raced and left to run out.
+        await Promise.race([sleep ? sleep(ms) : timerSleep(ms, left.signal), aborted]);
+    }
+    finally {
+        left.abort();
+    }
+}
+/** `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. */
+export async function fetchWithRetry(url, init, policy) {
+    const fetchFn = policy.fetchFn ?? fetch;
+    const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
+    const baseDelayMs = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const maxDelayMs = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const random = policy.random ?? Math.random;
+    const retryOn = policy.retryOn ?? ((res) => isRetryableStatus(res.status));
+    const retryTransport = policy.retryTransport ?? isIdempotent(init.method);
+    // Jitter over the upper half keeps parallel callers from retrying in lockstep.
+    const backoffMs = (attempt) => {
+        const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+        return ceiling / 2 + random() * (ceiling / 2);
+    };
+    for (let attempt = 1;; attempt++) {
+        const timeout = AbortSignal.timeout(policy.timeoutMs);
+        const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+        let res;
+        try {
+            res = await fetchFn(url, { ...init, signal });
+        }
+        catch (err) {
+            // The caller's own abort is a decision, not a fault, so it ends the call.
+            if (!retryTransport || attempt >= attempts || init.signal?.aborted || !isTransientTransportError(err))
+                throw err;
+            await backoffWait(backoffMs(attempt), policy.sleep, init.signal);
+            continue;
+        }
+        if (!retryOn(res) || attempt >= attempts)
+            return res;
+        const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
+        if (retryAfter !== null && retryAfter > maxDelayMs)
+            return res;
+        // Frees the pooled socket before the next attempt.
+        await res.body?.cancel();
+        await backoffWait(retryAfter ?? backoffMs(attempt), policy.sleep, init.signal);
+    }
+}
+//# sourceMappingURL=http-retry.js.map

package/dist/{http-util.d.ts → util/http-util.d.ts}

@@ -1,7 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { JsonValue } from './json.js';
-export declare function isJsonObjectRecord(value: JsonValue | undefined): value is Record<string, JsonValue>;
 export declare function isHeaderString(value: string | string[] | undefined): value is string;
+export declare const MAX_BODY_BYTES: number;
 export declare const MAX_ID_LEN = 256;
 export declare const JSON_HEADERS: {
     readonly 'content-type': "application/json";
@@ -12,6 +11,11 @@ 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. */
+export declare class DeadlineExceededError extends HttpError {
+    readonly code = "deadline_exceeded";
+    constructor(message: string);
+}
 export declare class BodyTooLargeError extends Error {
 }
 /** The body did not arrive in time. Its own class so mapApiError answers 408 and the server drops the socket. */
@@ -29,10 +33,12 @@ export declare const STORE_NOT_PORTED_MESSAGE = "store_not_ported";
 export declare function mapApiError<E>(err: E): ApiErrorReply;
 /** 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. */
+export declare function bodyDeadlineMs(): number;
 export interface ReadBodyOpts {
     /** Defaults to 1 MB. */
     maxBytes?: number;
-    /** Fails with BodyTimeoutError when the whole body has not arrived by then; unset waits for as long as the socket stays open. */
+    /** 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. */
@@ -47,6 +53,11 @@ export interface WebhookRequest {
     res: ServerResponse;
     opts: {
         hippoRoot: string;
+        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. */
+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. */
+export declare function readWebhookBody({ req, opts }: WebhookRequest): Promise<string>;
 //# sourceMappingURL=http-util.d.ts.map

package/dist/{http-util.js → util/http-util.js}

@@ -1,9 +1,7 @@
-import { ApiError } from './api-errors.js';
-import { SqliteBlockedError } from './db/sqlite-blocked.js';
+import { ApiError } from '../core/api-errors.js';
+import { SqliteBlockedError } from './sqlite-blocked.js';
+import { envBodyTimeoutMs } from './env.js';
 // Leaf module shared by server.ts and the connector webhook receivers; it must not import either.
-export function isJsonObjectRecord(value) {
-    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
-}
 // node:http header values are `string | string[] | undefined` (never a bare
 // unknown), so this gets its own predicate rather than reusing isJsonString.
 export function isHeaderString(value) {
@@ -11,7 +9,7 @@ export function isHeaderString(value) {
 }
 // 1 MB body cap. The CLI never sends payloads near this; anything bigger is
 // almost certainly a misconfigured client or a deliberate memory-blowup attempt.
-const MAX_BODY_BYTES = 1024 * 1024;
+export const MAX_BODY_BYTES = 1024 * 1024;
 function sizeLabel(bytes) {
     return bytes % (1024 * 1024) === 0 ? `${bytes / (1024 * 1024)}MB` : `${Math.ceil(bytes / 1024)}KB`;
 }
@@ -30,6 +28,13 @@ 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. */
+export class DeadlineExceededError extends HttpError {
+    code = 'deadline_exceeded';
+    constructor(message) {
+        super(504, message);
+    }
+}
 export class BodyTooLargeError extends Error {
 }
 /** The body did not arrive in time. Its own class so mapApiError answers 408 and the server drops the socket. */
@@ -62,12 +67,16 @@ export function sendJson(res, status, body) {
     res.writeHead(status, JSON_HEADERS);
     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. */
+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. */
-export function readBody(req, { maxBytes = MAX_BODY_BYTES, deadlineMs } = {}) {
+export function readBody(req, { maxBytes = MAX_BODY_BYTES, deadlineMs = bodyDeadlineMs() } = {}) {
     return new Promise((resolve, reject) => {
         const chunks = [];
         let total = 0;
-        let timer;
         const refuse = (err) => {
             clearTimeout(timer);
             req.off('data', onData);
@@ -83,9 +92,7 @@ export function readBody(req, { maxBytes = MAX_BODY_BYTES, deadlineMs } = {}) {
             }
             refuse(new BodyTooLargeError(`request body exceeds ${sizeLabel(maxBytes)}`));
         };
-        if (deadlineMs !== undefined) {
-            timer = setTimeout(() => refuse(new BodyTimeoutError(`request body not received within ${deadlineMs} ms`)), deadlineMs);
-        }
+        const timer = setTimeout(() => refuse(new BodyTimeoutError(`request body not received within ${deadlineMs} ms`)), deadlineMs);
         req.on('data', onData);
         req.once('end', () => {
             clearTimeout(timer);
@@ -116,4 +123,17 @@ export function isCrossSite(req) {
     const origin = req.headers.origin;
     return origin !== undefined && origin !== `http://${req.headers.host}`;
 }
+// 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. */
+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. */
+export function readWebhookBody({ req, opts }) {
+    return readBody(req, { deadlineMs: opts.webhookBodyDeadlineMs ?? WEBHOOK_BODY_DEADLINE_MS });
+}
 //# sourceMappingURL=http-util.js.map

package/dist/util/json.d.ts

@@ -0,0 +1,17 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function isJsonString(value: JsonValue | undefined): value is string;
+export declare function isJsonNumber(value: JsonValue | undefined): value is number;
+export declare function isJsonBoolean(value: JsonValue | undefined): value is boolean;
+/** A non-null, non-array object. */
+export declare function isJsonObject(value: JsonValue | undefined): value is {
+    [key: string]: JsonValue;
+};
+/** Like `isJsonObject`, but also false for an object whose own `constructor` key shadows `Object`. */
+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. */
+export declare function readJsonFile(file: string): JsonValue;
+//# sourceMappingURL=json.d.ts.map

package/dist/util/json.js

@@ -0,0 +1,25 @@
+// Leaf module: the one value space JSON.parse can produce, so boundary guards narrow a shared type.
+import * as fs from 'fs';
+export function isJsonString(value) {
+    return typeof value === 'string';
+}
+export function isJsonNumber(value) {
+    return typeof value === 'number';
+}
+export function isJsonBoolean(value) {
+    return typeof value === 'boolean';
+}
+/** A non-null, non-array object. */
+export function isJsonObject(value) {
+    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Like `isJsonObject`, but also false for an object whose own `constructor` key shadows `Object`. */
+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. */
+export function readJsonFile(file) {
+    const text = fs.readFileSync(file, 'utf8');
+    return JSON.parse(text.codePointAt(0) === 0xfeff ? text.slice(1) : text);
+}
+//# sourceMappingURL=json.js.map

package/dist/{log.d.ts → util/log.d.ts}

@@ -1,7 +1,9 @@
-/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. */
+/** 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; `requestId` ties a line to one HTTP request. */
+/** 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;
     [key: string]: string | number | boolean | undefined;
 }
@@ -10,7 +12,9 @@ export declare function logThreshold(): LogLevel;
 export declare function isLevelEnabled(level: LogLevel): boolean;
 /** Same `[hippo] ` prefix the existing stderr lines use, so default-level output reads as before. */
 export declare function formatLogLine(level: LogLevel, message: string, fields?: LogFields): string;
-/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
+/** 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. */
 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. */
 declare function warnThenDebug(key: string, message: string, fields?: LogFields): void;

package/dist/{log.js → util/log.js}

@@ -1,5 +1,7 @@
-/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. */
-import { envLogLevel } from './env.js';
+/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info,
+ * debug); unset or unknown means warn. `HIPPO_LOG_FORMAT=json` writes JSON lines. */
+import { envLogJson, envLogLevel } from './env.js';
+import { currentRequestId } from './request-scope.js';
 const RANK = { error: 0, warn: 1, info: 2, debug: 3 };
 function isLogLevel(value) {
     return Object.hasOwn(RANK, value);
@@ -22,24 +24,46 @@ export function formatLogLine(level, message, fields = {}) {
         .join('');
     return `[hippo] ${level}: ${oneLine(message)}${extras}`;
 }
+/** One JSON object per line for a log collector; JSON escaping keeps a multi-line value on the one line. */
+export function formatLogJson(level, message, fields = {}) {
+    const { ts, ...rest } = fields;
+    return JSON.stringify({ ts, level, msg: message, ...rest });
+}
 function write(level, message, fields) {
     if (!isLevelEnabled(level))
         return;
-    process.stderr.write(`${formatLogLine(level, message, fields)}\n`);
+    // The request id is ambient, so a line logged deep in a library call still names the request it ran for.
+    const stamped = { ts: new Date().toISOString(), requestId: currentRequestId(), ...fields };
+    const format = envLogJson() ? formatLogJson : formatLogLine;
+    process.stderr.write(`${format(level, message, stamped)}\n`);
 }
+// Some keys follow the data (one per damaged row and column), so the set of them stops growing here.
+const ONCE_KEY_CAP = 1_000;
 const onceKeys = new Set();
-/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
-function once(key, level, message, fields) {
+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. */
+function sightOnceKey(key) {
     if (onceKeys.has(key))
-        return;
-    onceKeys.add(key);
-    write(level, message, fields);
+        return 'seen';
+    if (onceKeys.size < ONCE_KEY_CAP) {
+        onceKeys.add(key);
+        return 'new';
+    }
+    if (!onceCapReported) {
+        onceCapReported = true;
+        write('warn', `log: ${ONCE_KEY_CAP} once-only warnings were written; further new ones in this process log at debug`);
+    }
+    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. */
+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. */
 function warnThenDebug(key, message, fields) {
-    const level = onceKeys.has(key) ? 'debug' : 'warn';
-    onceKeys.add(key);
-    write(level, message, fields);
+    write(sightOnceKey(key) === 'new' ? 'warn' : '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) {
@@ -62,5 +86,6 @@ export function errorMessage(cause) {
 /** Test hook: forget which once-keys have fired. */
 export function resetLogOnce() {
     onceKeys.clear();
+    onceCapReported = false;
 }
 //# sourceMappingURL=log.js.map

package/dist/util/real-path.d.ts

@@ -0,0 +1,3 @@
+/** Dereferences symlinks and junctions and normalises case on Windows; falls back to path.resolve when the path does not exist yet. */
+export declare function realpathOrResolve(p: string): string;
+//# sourceMappingURL=real-path.d.ts.map

package/dist/util/real-path.js

@@ -0,0 +1,15 @@
+// Leaf module: path canonicalisation shared by project identity and the importers.
+import * as fs from 'fs';
+import * as path from 'path';
+import { errorMessage, log } from './log.js';
+/** Dereferences symlinks and junctions and normalises case on Windows; falls back to path.resolve when the path does not exist yet. */
+export function realpathOrResolve(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch (err) {
+        log.debug(`realpath fell back to resolve for ${p}: ${errorMessage(err)}`);
+        return path.resolve(p);
+    }
+}
+//# sourceMappingURL=real-path.js.map

package/dist/util/request-scope.d.ts

@@ -0,0 +1,28 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** What every scope carries; the store layer's RequestStores is one, and adds its handles. */
+export interface RequestScope {
+    /** Ties every log line written inside the scope to one request. */
+    readonly requestId: string | undefined;
+    /** Set for a served request that must be answered by a given time. */
+    readonly deadline?: RequestDeadline | undefined;
+}
+/** When a request must be answered, and the store calls it still waits on: the store ends each of those soon after `at`, with the outcome only it knows. */
+export declare class RequestDeadline {
+    #private;
+    /** Epoch milliseconds. */
+    readonly at: number;
+    constructor(at: number);
+    /** Counts `call` as one the request waits on until it settles. */
+    track<T>(call: Promise<T>): Promise<T>;
+    /** Runs `fn` now, or once the last store call the request waits on has settled. */
+    onceIdle(fn: () => void): void;
+}
+export declare const requestScopes: AsyncLocalStorage<RequestScope>;
+/** The id of the request this code runs for, if any. */
+export declare function currentRequestId(): string | undefined;
+/** The deadline of the request this code runs for, if it has one. */
+export declare function currentDeadline(): RequestDeadline | undefined;
+/** Runs `fn` with `requestId` on every log line it writes, including the ones from
+ * timers and promises it starts. `deadline` reaches every store call made inside. */
+export declare function runWithRequestId<T>(requestId: string, fn: () => T, deadline?: RequestDeadline): T;
+//# sourceMappingURL=request-scope.d.ts.map

package/dist/util/request-scope.js

@@ -0,0 +1,48 @@
+// The one ambient scope of a request. A leaf module, so the logger can read the request id without importing the store layer.
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** When a request must be answered, and the store calls it still waits on: the store ends each of those soon after `at`, with the outcome only it knows. */
+export class RequestDeadline {
+    /** Epoch milliseconds. */
+    at;
+    #storeCalls = 0;
+    #whenIdle;
+    constructor(at) {
+        this.at = at;
+    }
+    /** Counts `call` as one the request waits on until it settles. */
+    track(call) {
+        this.#storeCalls += 1;
+        const done = () => {
+            this.#storeCalls -= 1;
+            if (this.#storeCalls > 0)
+                return;
+            const idle = this.#whenIdle;
+            this.#whenIdle = undefined;
+            idle?.();
+        };
+        call.then(done, done);
+        return call;
+    }
+    /** Runs `fn` now, or once the last store call the request waits on has settled. */
+    onceIdle(fn) {
+        if (this.#storeCalls === 0)
+            fn();
+        else
+            this.#whenIdle = fn;
+    }
+}
+export const requestScopes = new AsyncLocalStorage();
+/** The id of the request this code runs for, if any. */
+export function currentRequestId() {
+    return requestScopes.getStore()?.requestId;
+}
+/** The deadline of the request this code runs for, if it has one. */
+export function currentDeadline() {
+    return requestScopes.getStore()?.deadline;
+}
+/** Runs `fn` with `requestId` on every log line it writes, including the ones from
+ * timers and promises it starts. `deadline` reaches every store call made inside. */
+export function runWithRequestId(requestId, fn, deadline) {
+    return requestScopes.run({ requestId, deadline }, fn);
+}
+//# sourceMappingURL=request-scope.js.map

package/dist/{same-text.d.ts → util/same-text.d.ts}

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from './memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 type Text = Pick<MemoryEntry, 'content'> & {
     source?: string;
     pinned?: boolean;

package/dist/{secret-detect.d.ts → util/secret-detect.d.ts}

@@ -1,22 +1,5 @@
-/**
- * Secret detection for memory content (memory scope isolation).
- *
- * Conservative, provider-bounded patterns only - a bare `sk-` in prose must
- * NOT flag. Detection gates two surfaces:
- *  - producer: shareMemory/autoShare never promote flagged rows to the
- *    global store;
- *  - consumer: ambient context (getContext) never injects a flagged row
- *    outside its owning project, and never anywhere when the row has no
- *    project origin. Explicit recall is unaffected - recalling a secret is
- *    a deliberate act.
- *
- * This is deliberately a thin slice of lifecycle compliance
- * (no PII detection). Write-time scrubbing covers only text no person
- * typed into hippo; see `vetSecrets`.
- *
- * Leaf module: keep free of imports from store/api/shared so all of them
- * can import it without cycles.
- */
+/** Secret detection for memory content: conservative provider-bounded patterns (a bare `sk-` in prose must not flag). Flagged rows are never shared to
+ * the global store or injected as ambient context outside their project; explicit recall is unaffected. Leaf module: no imports from store/api/shared. */
 /** Result of scanning one memory. `reason` names the tag or pattern that fired. */
 export interface SecretDetection {
     flagged: boolean;
@@ -24,21 +7,13 @@ export interface SecretDetection {
 }
 /** Tags that flag a memory as secret, lower case; detectSecret folds a tag's case before the lookup. */
 export declare const SECRET_TAGS: ReadonlySet<string>;
-/**
- * Scan a memory's tags + content for secret material.
- * Pure and deterministic; no filesystem or store access.
- */
+/** Scan a memory's tags + content for secret material; pure and deterministic, no filesystem or store access. */
 export declare function detectSecret(entry: {
     content: string;
     tags: string[];
 }): SecretDetection;
-/**
- * Replace secret-shaped substrings in free text with a redaction marker.
- * Reuses the same `SECRET_PATTERNS` / co-occurrence guard as `detectSecret`
- * (which only flags whole-entry content) so callers that must persist raw
- * text that never passes through the normal capture content gate (e.g. the
- * pre-compact snapshot fields) can scrub it in place instead.
- */
+/** Replace secret-shaped substrings in free text with a redaction marker, using the same `SECRET_PATTERNS` and co-occurrence guard as `detectSecret`;
+ * for callers persisting text that skips the capture content gate (e.g. pre-compact snapshot fields). */
 export declare function redactSecrets(text: string): string;
 /** Memories never hold a raw email address (AGENTS.md); phone numbers are left alone, as their patterns misfire on ids. */
 export declare function maskEmails(text: string): string;