hippo-memory 1.70.0 → 1.72.0

package/dist/util/http-util.js

@@ -1,5 +1,3 @@
-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.
 // node:http header values are `string | string[] | undefined` (never a bare
@@ -15,8 +13,6 @@ function sizeLabel(bytes) {
 }
 // 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;
-// 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;
 export const JSON_HEADERS = { 'content-type': 'application/json' };
 export class HttpError extends Error {
     status;
@@ -43,22 +39,6 @@ export class BodyTimeoutError extends Error {
 export const INTERNAL_ERROR_MESSAGE = 'internal server error';
 /** The reply when a request under another store reaches code that still opens hippo.db. */
 export const STORE_NOT_PORTED_MESSAGE = 'store_not_ported';
-/** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
-export function mapApiError(err) {
-    // An add-on can build an HttpError from any number, and writeHead throws on one outside 100-999.
-    if (err instanceof HttpError && !(Number.isInteger(err.status) && err.status >= 100 && err.status <= 999)) {
-        return { status: 500, message: INTERNAL_ERROR_MESSAGE };
-    }
-    if (err instanceof HttpError || err instanceof ApiError)
-        return { status: err.status, message: err.message };
-    if (err instanceof BodyTooLargeError)
-        return { status: 413, message: err.message };
-    if (err instanceof BodyTimeoutError)
-        return { status: 408, message: err.message };
-    if (err instanceof SqliteBlockedError)
-        return { status: 501, message: STORE_NOT_PORTED_MESSAGE };
-    return { status: 500, message: INTERNAL_ERROR_MESSAGE };
-}
 /** Serialises before the head goes out, so a body that is not JSON still reaches the caller's error reply. */
 export function sendJson(res, status, body) {
     const text = JSON.stringify(body);
@@ -121,7 +101,16 @@ export function isCrossSite(req) {
     if (site !== undefined && site !== 'same-origin' && site !== 'none')
         return true;
     const origin = req.headers.origin;
-    return origin !== undefined && origin !== `http://${req.headers.host}`;
+    return origin !== undefined && originHost(origin) !== req.headers.host;
+}
+// Scheme is ignored so an https page behind a TLS-terminating proxy still matches its own Host.
+function originHost(origin) {
+    try {
+        return new URL(origin).host;
+    }
+    catch {
+        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.
 const WEBHOOK_BODY_DEADLINE_MS = 10_000;

package/dist/util/limits.d.ts

@@ -0,0 +1,7 @@
+export declare const MAX_ID_LEN = 256;
+export declare const DEFAULT_LIST_LIMIT = 100;
+export declare 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. */
+export declare function resolveListLimit(requested: number | undefined, defaultLimit?: number, maxLimit?: number): number | undefined;
+//# sourceMappingURL=limits.d.ts.map

package/dist/util/limits.js

@@ -0,0 +1,14 @@
+// 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.
+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. */
+export function resolveListLimit(requested, defaultLimit = DEFAULT_LIST_LIMIT, maxLimit = Infinity) {
+    if (requested === undefined)
+        return defaultLimit;
+    return Number.isInteger(requested) && requested > 0 && requested <= maxLimit ? requested : undefined;
+}
+//# sourceMappingURL=limits.js.map

package/dist/util/log.d.ts

@@ -1,4 +1,5 @@
-/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. `HIPPO_LOG_FORMAT=json` writes JSON lines. */
+/** 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. */
 export interface LogFields {
@@ -13,7 +14,7 @@ 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. */
+/** 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;
@@ -29,6 +30,10 @@ export declare const log: {
 };
 /** 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;
+/** 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. */
 export declare function resetLogOnce(): void;
 export {};

package/dist/util/log.js

@@ -1,4 +1,5 @@
-/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. `HIPPO_LOG_FORMAT=json` writes JSON lines. */
+/** 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 };
@@ -36,19 +37,33 @@ function write(level, message, 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) {
@@ -68,8 +83,18 @@ export const log = {
 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) {
+    say(`${step} failed: ${reason}`);
+    log.error(`post-compact: ${step} failed: ${reason}`);
+}
+/** The string `code` of a caught value (an errno name such as EACCES), or '' when it has none. */
+export function errorCode(cause) {
+    return cause instanceof Error && 'code' in cause ? String(cause.code) : '';
+}
 /** Test hook: forget which once-keys have fired. */
 export function resetLogOnce() {
     onceKeys.clear();
+    onceCapReported = false;
 }
 //# sourceMappingURL=log.js.map

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

@@ -6,6 +6,8 @@ export interface RequestScope {
     /** Set for a served request that must be answered by a given time. */
     readonly deadline?: RequestDeadline | undefined;
 }
+/** How long a request may run: 120 s, or HIPPO_REQUEST_DEADLINE_MS, where 0 turns the deadline off. */
+export declare function requestDeadlineMs(): number;
 /** 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;
@@ -14,7 +16,7 @@ export declare class RequestDeadline {
     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. */
+    /** Runs `fn` now, or once the last store call the request waits on has settled; every function registered meanwhile runs, in order. */
     onceIdle(fn: () => void): void;
 }
 export declare const requestScopes: AsyncLocalStorage<RequestScope>;
@@ -22,6 +24,7 @@ export declare const requestScopes: AsyncLocalStorage<RequestScope>;
 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. */
+/** 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

@@ -1,11 +1,17 @@
 // 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';
+import { envRequestDeadlineMs } from './env.js';
+const DEFAULT_REQUEST_DEADLINE_MS = 120_000;
+/** How long a request may run: 120 s, or HIPPO_REQUEST_DEADLINE_MS, where 0 turns the deadline off. */
+export function requestDeadlineMs() {
+    return envRequestDeadlineMs() ?? DEFAULT_REQUEST_DEADLINE_MS;
+}
 /** 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;
+    #whenIdle = [];
     constructor(at) {
         this.at = at;
     }
@@ -16,19 +22,18 @@ export class RequestDeadline {
             this.#storeCalls -= 1;
             if (this.#storeCalls > 0)
                 return;
-            const idle = this.#whenIdle;
-            this.#whenIdle = undefined;
-            idle?.();
+            for (const idle of this.#whenIdle.splice(0))
+                idle();
         };
         call.then(done, done);
         return call;
     }
-    /** Runs `fn` now, or once the last store call the request waits on has settled. */
+    /** Runs `fn` now, or once the last store call the request waits on has settled; every function registered meanwhile runs, in order. */
     onceIdle(fn) {
         if (this.#storeCalls === 0)
             fn();
         else
-            this.#whenIdle = fn;
+            this.#whenIdle.push(fn);
     }
 }
 export const requestScopes = new AsyncLocalStorage();
@@ -40,7 +45,8 @@ export function currentRequestId() {
 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. */
+/** 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);
 }

package/dist/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;

package/dist/util/secret-detect.js

@@ -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. */
 /** Tags that flag a memory as secret, lower case; detectSecret folds a tag's case before the lookup. */
 export const SECRET_TAGS = new Set([
     'secret', 'api-key', 'apikey', 'credential', 'credentials',
@@ -26,7 +9,8 @@ const SECRET_PATTERNS = [
     { name: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
     { name: 'github-token', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b/ },
     { name: 'github-fine-grained-pat', re: /\bgithub_pat_[A-Za-z0-9_]{22,}\b/ },
-    // A token may end in a hyphen, where `\b` holds only before a word character: a class that holds `-` runs to its end, and a fixed length may also close on a hyphen.
+    // A token may end in a hyphen, where `\b` holds only before a word character: a class
+    // that holds `-` runs to its end, and a fixed length may also close on a hyphen.
     { name: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ },
     { name: 'stripe-key', re: /\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}\b/ },
     { name: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}(?:\b|(?<=-))/ },
@@ -38,16 +22,18 @@ const SECRET_PATTERNS = [
     { name: 'google-oauth-token', re: /\bya29\.[\w-]{20,}/ },
     { name: 'slack-webhook', re: /\bhooks\.slack\.com\/(?:services|workflows|triggers)\/[A-Za-z0-9+/]{43,56}/ },
     { name: 'private-key-block', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
-    // sk-... (OpenAI/Anthropic style) and sk_<vendor>_... shapes. Both require
-    // a key-ish noun somewhere in the content (co-occurrence guard) so prose
-    // like "the sk- prefix identifies API keys" without an actual long token
-    // does not flag, but a stored key ("prod API key sk_live_...")
-    // does.
+    // sk-... (OpenAI/Anthropic) and sk_<vendor>_... shapes; both need a key-ish noun in the content (co-occurrence guard), so prose
+    // like "the sk- prefix identifies API keys" does not flag but "prod API key sk_live_..." does.
     { name: 'sk-style-key', re: /\bsk-[A-Za-z0-9_-]{20,}/ },
     { name: 'sk-underscore-key', re: /\bsk_[A-Za-z0-9]+_[A-Za-z0-9_]{6,}\b/ },
-    // The value needs 12+ token-safe chars and a digit, or `token = estimateTokens(...)` and doc templates like user:password@ would hide code lessons from ambient context.
-    // Secret names end in the keyword (dbPassword, PGPASSWORD) and token_url does not, so the match opens there and scans no prefix; pwd and pass need a _ as OLDPWD and bypass are not secrets.
-    { name: 'secret-assignment', re: /(?:(?:api[_-]?key|access[_-]?key|private[_-]?key|secret|token|passw(?:or)?d|(?<=_)(?:pwd|pass))(?:[_-]?(?:key(?:[_-]?base)?|value|secret))?['"]?\s*(?::=?|=>?)\s*['"]?|(?<=--)password(?:=|\s+))(?=[A-Za-z0-9_\-+/]*\d)[A-Za-z0-9_\-+/=]{12,}/i },
+    // Value needs 12+ token-safe chars and a digit, or `token = estimateTokens(...)` and user:password@ templates would hide code lessons from ambient context.
+    // Secret names end in the keyword (dbPassword), so the match opens there, no prefix scan; pwd and pass need a _ (OLDPWD, bypass are not secrets).
+    {
+        name: 'secret-assignment',
+        re: new RegExp(String.raw `(?:(?:api[_-]?key|access[_-]?key|private[_-]?key|secret|token|passw(?:or)?d|(?<=_)(?:pwd|pass))` +
+            String.raw `(?:[_-]?(?:key(?:[_-]?base)?|value|secret))?['"]?\s*(?::=?|=>?)\s*['"]?|(?<=--)password(?:=|\s+))` +
+            String.raw `(?=[A-Za-z0-9_\-+/]*\d)[A-Za-z0-9_\-+/=]{12,}`, 'i'),
+    },
     { name: 'url-password', re: /(?<=[A-Za-z0-9]:\/\/)[^\s/:@?#]*:(?=[^\s/@?#]*\d)[^\s/@?#]+(?=@)/ },
 ];
 const KEYISH_CONTEXT_RE = /key|token|secret|credential|bearer|auth|password/i;
@@ -59,10 +45,7 @@ const STRICT_ONLY_PATTERNS = [
     /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*/g,
     /(?<=[A-Za-z0-9]:\/\/)[^\s/:@?#]*:[^\s/@?#]+(?=@)/g,
 ];
-/**
- * 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 function detectSecret(entry) {
     for (const tag of entry.tags) {
         if (SECRET_TAGS.has(tag.toLowerCase())) {
@@ -78,17 +61,13 @@ export function detectSecret(entry) {
     }
     return { flagged: false, reason: null };
 }
-/**
- * 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 function redactSecrets(text) {
     return redactText(text, false);
 }
-/** Only a run's first character starts a match, so a long run is scanned once; a domain's first label opens on a letter, so logo@2x.png and react@18.2.0 stay. */
+/** Only a run's first character starts a match, so a long run is scanned once; a
+ * domain's first label opens on a letter, so logo@2x.png and react@18.2.0 stay. */
 const EMAIL = /(?<![A-Za-z0-9._%+-])[A-Za-z0-9._%+-]{1,64}@[A-Za-z][A-Za-z0-9-]*(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}\b/g;
 /** Memories never hold a raw email address (AGENTS.md); phone numbers are left alone, as their patterns misfire on ids. */
 export function maskEmails(text) {

package/dist/util/sqlite-blocked.d.ts

@@ -13,4 +13,6 @@ export declare class OtherStoreFolderError extends SqliteBlockedError {
     readonly markerPath: string;
     constructor(storeKind: string, markerPath: string);
 }
+/** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
+export declare function rethrowIfSqliteBlocked<E>(err: E): void;
 //# sourceMappingURL=sqlite-blocked.d.ts.map

package/dist/util/sqlite-blocked.js

@@ -26,4 +26,9 @@ export class OtherStoreFolderError extends SqliteBlockedError {
         this.name = 'OtherStoreFolderError';
     }
 }
+/** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
+export function rethrowIfSqliteBlocked(err) {
+    if (err instanceof SqliteBlockedError)
+        throw err;
+}
 //# sourceMappingURL=sqlite-blocked.js.map

package/dist/util/stored-json.d.ts

@@ -4,6 +4,6 @@ export interface StoredJsonSite {
     id: string | number;
     column: string;
 }
-/** Warns the first time this row's column is found damaged, then logs at debug, so a row read on every recall cannot flood stderr. */
+/** Warns the first time this row's column is found damaged (the logger caps how many), then at debug, so a row read on every recall cannot flood stderr. */
 export declare function warnDamagedColumn(site: StoredJsonSite, problem: 'not valid JSON' | 'wrong shape'): void;
 //# sourceMappingURL=stored-json.d.ts.map

package/dist/util/stored-json.js

@@ -1,6 +1,6 @@
 // One log line for a stored JSON column that will not read, so a reader that degrades to an empty value still leaves a trace.
 import { log } from './log.js';
-/** Warns the first time this row's column is found damaged, then logs at debug, so a row read on every recall cannot flood stderr. */
+/** Warns the first time this row's column is found damaged (the logger caps how many), then at debug, so a row read on every recall cannot flood stderr. */
 export function warnDamagedColumn(site, problem) {
     const { table, id, column } = site;
     log.warnThenDebug(`damaged-column:${table}:${id}:${column}`, `store: ${table}.${column} is ${problem}; read as empty`, { table, id, column });

package/dist/util/stream-tee.d.ts

@@ -0,0 +1,3 @@
+/** Mirrors every stdout and stderr chunk to `logFile` until the returned restore runs; an append failure warns once and never stops the real write. */
+export declare function teeStdStreams(logFile: string): () => void;
+//# sourceMappingURL=stream-tee.d.ts.map

package/dist/util/stream-tee.js

@@ -0,0 +1,35 @@
+import * as fs from 'fs';
+import { errorMessage, log } from './log.js';
+/** Mirrors every stdout and stderr chunk to `logFile` until the returned restore runs; an append failure warns once and never stops the real write. */
+export function teeStdStreams(logFile) {
+    const origStdoutWrite = process.stdout.write.bind(process.stdout);
+    const origStderrWrite = process.stderr.write.bind(process.stderr);
+    let warned = false;
+    const tee = (chunk) => {
+        try {
+            fs.appendFileSync(logFile, chunk instanceof Uint8Array ? Buffer.from(chunk).toString('utf8') : chunk, 'utf8');
+        }
+        catch (err) {
+            if (warned)
+                return;
+            warned = true;
+            log.warn(`log file ${logFile} is no longer writable; output continues without it: ${errorMessage(err)}`);
+        }
+    };
+    const wrapWrite = (origWrite) => {
+        const wrapped = (...args) => {
+            tee(args[0]);
+            // SAFETY: forwarding the exact arguments the real overloaded `write` received is safe; `StreamWriteArgs` is the union of both overloads' parameter lists.
+            return origWrite(...args);
+        };
+        // SAFETY: `wrapped` matches both real `write` overload shapes; TS cannot verify one implementation covers an overloaded type.
+        return wrapped;
+    };
+    process.stdout.write = wrapWrite(origStdoutWrite);
+    process.stderr.write = wrapWrite(origStderrWrite);
+    return () => {
+        process.stdout.write = origStdoutWrite;
+        process.stderr.write = origStderrWrite;
+    };
+}
+//# sourceMappingURL=stream-tee.js.map

package/dist/util/time.d.ts

@@ -1,2 +1,6 @@
 export declare const DAY_MS = 86400000;
+export declare const MINUTE_MS = 60000;
+export declare const HOUR_MS = 3600000;
+/** One 365-day year in seconds. */
+export declare const YEAR_S = 31536000;
 //# sourceMappingURL=time.d.ts.map

package/dist/util/time.js

@@ -1,3 +1,7 @@
 // Durations in the base layer, so no layer imports a higher one for a constant.
 export const DAY_MS = 86_400_000;
+export const MINUTE_MS = 60_000;
+export const HOUR_MS = 3_600_000;
+/** One 365-day year in seconds. */
+export const YEAR_S = 31_536_000;
 //# sourceMappingURL=time.js.map

package/dist/util/token-text.d.ts

@@ -8,10 +8,7 @@ export declare const DIGEST_DISPLAY_CHARS = 12;
 export declare const DATE_PREFIX_CHARS = 10;
 /** Characters of memory content shown as a one-line preview. */
 export declare const CONTENT_PREVIEW_CHARS = 80;
-/**
- * Rough token estimate: characters / 4. The single estimate behind every
- * token budget and ledger count in hippo.
- */
+/** Rough token estimate: characters / 4, the single estimate behind every token budget and ledger count. */
 export declare function estimateTokens(text: string): number;
 /** Stable 16-hex-char hash of a rendered block, for change detection. */
 export declare function blockHash(text: string): string;

package/dist/util/token-text.js

@@ -9,10 +9,7 @@ export const DIGEST_DISPLAY_CHARS = 12;
 export const DATE_PREFIX_CHARS = 10;
 /** Characters of memory content shown as a one-line preview. */
 export const CONTENT_PREVIEW_CHARS = 80;
-/**
- * Rough token estimate: characters / 4. The single estimate behind every
- * token budget and ledger count in hippo.
- */
+/** Rough token estimate: characters / 4, the single estimate behind every token budget and ledger count. */
 export function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }

package/dist/util/transcript-tail.d.ts

@@ -4,4 +4,6 @@ export declare const PRE_COMPACT_TAIL_BYTES: number;
 export declare function truncateCodePointSafe(text: string, maxChars: number): string;
 /** The last `capBytes` of a JSONL transcript, read at an offset and starting on a whole line so every line parses. */
 export declare function readTranscriptTail(transcriptPath: string, capBytes?: number): string;
+/** {@link readTranscriptTail} for a transcript the caller opened and sized, so the size and the bytes come from one file. */
+export declare function readOpenTranscriptTail(fd: number, size: number, capBytes: number): string;
 //# sourceMappingURL=transcript-tail.d.ts.map

package/dist/util/transcript-tail.js

@@ -1,4 +1,4 @@
-// Transcript reads shared by capture.ts and compaction-record.ts; a leaf so neither has to import the other.
+// Transcript reads shared by src/capture/ and compaction-record.ts; a leaf so neither has to import the other.
 import * as fs from 'fs';
 /** Never read the whole transcript: PreCompact fires exactly when it's largest. */
 export const PRE_COMPACT_TAIL_BYTES = 256 * 1024;
@@ -16,33 +16,34 @@ export function truncateCodePointSafe(text, maxChars) {
 }
 /** The last `capBytes` of a JSONL transcript, read at an offset and starting on a whole line so every line parses. */
 export function readTranscriptTail(transcriptPath, capBytes = PRE_COMPACT_TAIL_BYTES) {
-    const size = fs.statSync(transcriptPath).size;
-    const start = Math.max(0, size - capBytes);
-    const length = size - start;
-    if (length <= 0)
-        return '';
     const fd = fs.openSync(transcriptPath, 'r');
     try {
-        // A seek that lands just after '\n' already starts a whole line and must keep it.
-        let onLineBoundary = start === 0;
-        if (!onLineBoundary) {
-            const prevByte = Buffer.alloc(1);
-            fs.readSync(fd, prevByte, 0, 1, start - 1);
-            onLineBoundary = prevByte[0] === 0x0a; // '\n'
-        }
-        const buf = Buffer.alloc(length);
-        fs.readSync(fd, buf, 0, length, start);
-        let text = buf.toString('utf8');
-        if (!onLineBoundary) {
-            // Landed mid-line — drop the partial first line so every remaining
-            // line parses as complete JSON.
-            const nl = text.indexOf('\n');
-            text = nl === -1 ? '' : text.slice(nl + 1);
-        }
-        return text;
+        return readOpenTranscriptTail(fd, fs.fstatSync(fd).size, capBytes);
     }
     finally {
         fs.closeSync(fd);
     }
 }
+/** {@link readTranscriptTail} for a transcript the caller opened and sized, so the size and the bytes come from one file. */
+export function readOpenTranscriptTail(fd, size, capBytes) {
+    const start = Math.max(0, size - capBytes);
+    const length = size - start;
+    if (length <= 0)
+        return '';
+    // A seek that lands just after '\n' already starts a whole line and must keep it.
+    let onLineBoundary = start === 0;
+    if (!onLineBoundary) {
+        const prevByte = Buffer.alloc(1);
+        fs.readSync(fd, prevByte, 0, 1, start - 1);
+        onLineBoundary = prevByte[0] === 0x0a; // '\n'
+    }
+    const buf = Buffer.alloc(length);
+    fs.readSync(fd, buf, 0, length, start);
+    const text = buf.toString('utf8');
+    if (onLineBoundary)
+        return text;
+    // A read that lands mid-line drops the partial first line, so every line left parses as complete JSON.
+    const nl = text.indexOf('\n');
+    return nl === -1 ? '' : text.slice(nl + 1);
+}
 //# sourceMappingURL=transcript-tail.js.map

package/dist/util/version.d.ts

@@ -1,23 +1,8 @@
-/**
- * Single source of truth for the hippo-memory binary's package version.
- *
- * Written by `npm version <x> --no-git-tag-version` through
- * scripts/sync-version.mjs, with the three plugin manifests; never edit it by
- * hand. scripts/check-manifest-versions.mjs gates publish on all seven sites.
- *
- * Used by:
- *   - src/db/migrate.ts rollback-safety guard (refuses to open a DB stamped with
- *     min_compatible_binary newer than this).
- *   - src/server.ts HTTP /health.
- *   - src/mcp/server.ts MCP serverInfo.
- *
- * Why not read package.json at runtime: the npm-published bundle ships
- * compiled `dist/` files that may not have package.json on a relative path
- * an ESM `import` can resolve cleanly, and a hardcoded constant survives
- * any packager that drops .json files.
- */
-export declare const PACKAGE_VERSION = "1.70.0";
-/** The floor a store takes on its first expiring key: the first release with schema v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
+/** Single source of truth for the package version, written by scripts/sync-version.mjs; never edit by hand. Read by the db rollback guard, /health, MCP.
+ * A constant, not a runtime package.json read: the published bundle may lack package.json on a path ESM can resolve. */
+export declare const PACKAGE_VERSION = "1.72.0";
+/** The floor a store takes on its first expiring key: the first release with schema
+ * v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
 export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
 /** The floor a store takes on its first session bind or owner snapshot: first release with v54; set by hand in that release. */
 export declare const TASK_OWNER_MIN_BINARY = "1.64.0";