hippo-memory 1.71.0 → 2.0.0

package/dist/util/http-retry.js

@@ -1,13 +1,19 @@
 /** 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';
 const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_BASE_DELAY_MS = 250;
 const DEFAULT_MAX_DELAY_MS = 8_000;
-const DEFAULT_LLM_TIMEOUT_MS = 60_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. */
 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. */
+export function llmTotalMs() {
+    return 2 * llmTimeoutMs() + DEFAULT_MAX_DELAY_MS;
+}
 export function isRetryableStatus(status) {
     return status === 429 || (status >= 500 && status <= 599);
 }
@@ -39,6 +45,22 @@ function isIdempotent(method) {
     const verb = (method ?? 'GET').toUpperCase();
     return verb === 'GET' || verb === 'HEAD';
 }
+/** Host plus pathname only: a query string can carry a key. */
+function redactedTarget(url) {
+    try {
+        const u = new URL(url);
+        return `${u.host}${u.pathname}`;
+    }
+    catch {
+        return 'unparseable-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),
+    });
+}
 // `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);
@@ -71,13 +93,16 @@ export async function fetchWithRetry(url, init, policy) {
     const random = policy.random ?? Math.random;
     const retryOn = policy.retryOn ?? ((res) => isRetryableStatus(res.status));
     const retryTransport = policy.retryTransport ?? isIdempotent(init.method);
+    const now = policy.now ?? Date.now;
+    const deadline = policy.totalMs === undefined ? Infinity : now() + policy.totalMs;
+    const fitsBudget = (delayMs) => now() + delayMs < deadline;
     // 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 timeout = AbortSignal.timeout(Math.max(1, Math.min(policy.timeoutMs, deadline - now())));
         const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
         let res;
         try {
@@ -87,7 +112,11 @@ export async function fetchWithRetry(url, init, policy) {
             // 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);
+            const delay = backoffMs(attempt);
+            if (!fitsBudget(delay))
+                throw err;
+            logRetry(init, url, errorCode(err) || (err instanceof Error ? err.name : 'transport'), attempt, attempts, delay);
+            await backoffWait(delay, policy.sleep, init.signal);
             continue;
         }
         if (!retryOn(res) || attempt >= attempts)
@@ -95,9 +124,18 @@ export async function fetchWithRetry(url, init, policy) {
         const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
         if (retryAfter !== null && retryAfter > maxDelayMs)
             return res;
+        const delay = retryAfter ?? backoffMs(attempt);
+        if (!fitsBudget(delay))
+            return res;
         // Frees the pooled socket before the next attempt.
-        await res.body?.cancel();
-        await backoffWait(retryAfter ?? backoffMs(attempt), policy.sleep, init.signal);
+        try {
+            await res.body?.cancel();
+        }
+        catch (err) {
+            log.debug('http retry: body cancel failed', errorFields(err));
+        }
+        logRetry(init, url, `status ${res.status}`, attempt, attempts, delay);
+        await backoffWait(delay, policy.sleep, init.signal);
     }
 }
 //# sourceMappingURL=http-retry.js.map

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

@@ -1,7 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 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";
 };
@@ -21,16 +20,9 @@ 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. */
 export declare class BodyTimeoutError extends Error {
 }
-/** The status and client-facing message for one failed request. */
-export interface ApiErrorReply {
-    status: number;
-    message: string;
-}
 export declare const INTERNAL_ERROR_MESSAGE = "internal server error";
 /** The reply when a request under another store reaches code that still opens hippo.db. */
 export declare 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 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. */

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

@@ -30,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

@@ -83,6 +83,15 @@ 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();

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

@@ -5,7 +5,11 @@ export interface RequestScope {
     readonly requestId: string | undefined;
     /** Set for a served request that must be answered by a given time. */
     readonly deadline?: RequestDeadline | undefined;
+    /** Aborts when the request passes its deadline, so a handler that checks it stops starting work nobody waits for. */
+    readonly signal?: AbortSignal | 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 +18,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,7 +26,9 @@ 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;
+/** The abort signal of the request this code runs for, if it has one. */
+export declare function currentSignal(): AbortSignal | 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;
+ * timers and promises it starts. `deadline` reaches every store call made inside, and `signal` every check of `currentSignal`. */
+export declare function runWithRequestId<T>(requestId: string, fn: () => T, deadline?: RequestDeadline, signal?: AbortSignal): 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,9 +45,13 @@ export function currentRequestId() {
 export function currentDeadline() {
     return requestScopes.getStore()?.deadline;
 }
+/** The abort signal of the request this code runs for, if it has one. */
+export function currentSignal() {
+    return requestScopes.getStore()?.signal;
+}
 /** 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);
+ * timers and promises it starts. `deadline` reaches every store call made inside, and `signal` every check of `currentSignal`. */
+export function runWithRequestId(requestId, fn, deadline, signal) {
+    return requestScopes.run({ requestId, deadline, signal }, fn);
 }
 //# sourceMappingURL=request-scope.js.map

package/dist/util/secret-detect.js

@@ -28,7 +28,12 @@ const SECRET_PATTERNS = [
     { name: 'sk-underscore-key', re: /\bsk_[A-Za-z0-9]+_[A-Za-z0-9_]{6,}\b/ },
     // 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: /(?:(?: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 },
+    {
+        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;

package/dist/util/spawn-argv.d.ts

@@ -0,0 +1,9 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+/** Quotes one cmd.exe argument; each `%` leaves the quotes as `^%`, so no %NAME% pair can expand. */
+export declare function quoteCmdArg(arg: string): string;
+/** cmd.exe arguments that run a .cmd or .bat shim with every forwarded argument delivered verbatim. */
+export declare function cmdShimArgs(shimPath: string, forwardArgs: readonly string[]): string[];
+/** Spawns argv[0] with the rest as its arguments and no shell. Node refuses to start a .cmd or .bat without one (CVE-2024-27980),
+ *  so on win32 such a shim runs through cmd.exe with every argument quoted for it. */
+export declare function spawnArgv(argv: readonly string[], options: SpawnOptions): ChildProcess;
+//# sourceMappingURL=spawn-argv.d.ts.map

package/dist/util/spawn-argv.js

@@ -0,0 +1,57 @@
+// Starting a command from an argv list with no shell, Windows .cmd and .bat shims included, so no argument is ever parsed as shell syntax.
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { envPath, envPathExt } from './env.js';
+/** Quotes one cmd.exe argument; each `%` leaves the quotes as `^%`, so no %NAME% pair can expand. */
+export function quoteCmdArg(arg) {
+    if (arg.length === 0)
+        return '""';
+    if (!/[ \t"&()^<>|%!]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '""').replace(/%/g, '"^%"')}"`;
+}
+/** cmd.exe arguments that run a .cmd or .bat shim with every forwarded argument delivered verbatim. */
+export function cmdShimArgs(shimPath, forwardArgs) {
+    const command = `"${shimPath}"${forwardArgs.length > 0 ? ` ${forwardArgs.map(quoteCmdArg).join(' ')}` : ''}`;
+    // The line is already quoted for cmd.exe, so Node must not quote it again; /s strips the outer pair.
+    return ['/d', '/v:off', '/s', '/c', `"${command}"`];
+}
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+function isFile(candidate) {
+    return fs.statSync(candidate, { throwIfNoEntry: false })?.isFile() === true;
+}
+/** The file `command` names on win32: as given when it has a folder, else the first hit in the working folder then PATH, trying each PATHEXT. */
+function resolveWindowsCommand(command) {
+    const exts = (envPathExt() ?? DEFAULT_PATHEXT).split(';').filter((ext) => ext.length > 0);
+    const dirs = /[\\/]/.test(command) ? [''] : [process.cwd(), ...(envPath() ?? '').split(path.delimiter).filter((dir) => dir.length > 0)];
+    for (const dir of dirs) {
+        const base = dir === '' ? command : path.join(dir, command);
+        const candidates = path.extname(command) === '' ? exts.map((ext) => base + ext) : [base, ...exts.map((ext) => base + ext)];
+        const hit = candidates.find(isFile);
+        if (hit !== undefined)
+            return hit;
+    }
+    return null;
+}
+/** Spawns argv[0] with the rest as its arguments and no shell. Node refuses to start a .cmd or .bat without one (CVE-2024-27980),
+ *  so on win32 such a shim runs through cmd.exe with every argument quoted for it. */
+export function spawnArgv(argv, options) {
+    const [command, ...args] = argv;
+    if (command === undefined || command.length === 0)
+        throw new RangeError('spawnArgv needs a command: argv is empty');
+    if (process.platform === 'win32') {
+        const resolved = resolveWindowsCommand(command);
+        const ext = resolved === null ? '' : path.extname(resolved).toLowerCase();
+        if (resolved !== null && (ext === '.cmd' || ext === '.bat')) {
+            return spawn('cmd.exe', cmdShimArgs(resolved, args), {
+                ...options,
+                windowsHide: options.windowsHide ?? true,
+                shell: false,
+                windowsVerbatimArguments: true,
+            });
+        }
+    }
+    return spawn(command, args, { ...options, windowsHide: options.windowsHide ?? true, shell: false });
+}
+//# sourceMappingURL=spawn-argv.js.map

package/dist/util/sql.d.ts

@@ -0,0 +1,3 @@
+/** `n` bound-parameter marks joined for an IN list or VALUES row, e.g. 3 -> "?, ?, ?". */
+export declare function placeholders(n: number): string;
+//# sourceMappingURL=sql.d.ts.map

package/dist/util/sql.js

@@ -0,0 +1,6 @@
+// SQL text helpers shared by every layer that builds an IN list or VALUES row.
+/** `n` bound-parameter marks joined for an IN list or VALUES row, e.g. 3 -> "?, ?, ?". */
+export function placeholders(n) {
+    return Array.from({ length: n }, () => '?').join(', ');
+}
+//# sourceMappingURL=sql.js.map

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/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/vector-codec.d.ts

@@ -0,0 +1,4 @@
+/** Float32 vector <-> Buffer codec for BLOB columns. */
+export declare function float32ToBuffer(arr: number[]): Buffer;
+export declare function bufferToFloat32(buf: Buffer | Uint8Array): number[];
+//# sourceMappingURL=vector-codec.d.ts.map

package/dist/util/vector-codec.js

@@ -0,0 +1,15 @@
+/** Float32 vector <-> Buffer codec for BLOB columns. */
+export function float32ToBuffer(arr) {
+    const f32 = new Float32Array(arr);
+    return Buffer.from(f32.buffer);
+}
+export function bufferToFloat32(buf) {
+    if (buf.byteLength === 0 || buf.byteLength % 4 !== 0)
+        return [];
+    // Ensure we have a properly aligned copy (SQLite may return Uint8Array, not Buffer)
+    const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    const aligned = new ArrayBuffer(bytes.length);
+    new Uint8Array(aligned).set(bytes);
+    return Array.from(new Float32Array(aligned));
+}
+//# sourceMappingURL=vector-codec.js.map

package/dist/util/version.d.ts

@@ -1,6 +1,6 @@
 /** 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.71.0";
+export declare const PACKAGE_VERSION = "2.0.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";

package/dist/util/version.js

@@ -1,6 +1,6 @@
 /** 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 const PACKAGE_VERSION = '1.71.0';
+export const PACKAGE_VERSION = '2.0.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 const EXPIRING_KEYS_MIN_BINARY = '1.64.0';

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
-  "version": "1.71.0",
+  "version": "2.0.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.71.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
-  "version": "1.71.0",
+  "version": "2.0.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.71.0",
+  "version": "2.0.0",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",
@@ -8,6 +8,8 @@
   "exports": {
     ".": "./dist/index.js",
     "./server": "./dist/server.js",
+    "./store-kit": "./dist/entry/store-kit.js",
+    "./testing": "./dist/entry/testing.js",
     "./project-identity": "./dist/entry/project-identity.js",
     "./json-hooks": "./dist/entry/json-hooks.js",
     "./session-text": "./dist/entry/session-text.js"
@@ -39,7 +41,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:delivery-ledger": "vitest run tests/delivery-ledger",
+    "test:delivery-ledger": "vitest run tests/delivery-ledger tests/migration-v55",
     "test:eval": "vitest run --config vitest.eval.config.ts",
     "lint": "oxlint",
     "sbom": "node scripts/sbom.mjs",

package/dist/api/on-store.d.ts

@@ -1,16 +0,0 @@
-import type { HippoStore, StoreGroups } from '../store/port.js';
-import { type SqliteLocal } from '../store/sqlite/local.js';
-import { type SqliteSyncStore } from '../store/sqlite/store.js';
-import type { Context, StoreReply } from './types.js';
-/** What a port call answers: a Promise from a served store, the value itself from hippo.db. */
-export type Reply<T> = T | Promise<T>;
-/** The port one body is written against: a served store, or hippo.db answering the same methods at once. */
-export type StorePort = HippoStore | SqliteSyncStore;
-/** `next` on the reply's value, at once for a value, so hippo.db's path never becomes a Promise. */
-export declare function andThen<T, U>(reply: Reply<T>, next: (value: T) => Reply<U>): Reply<U>;
-/** Stands in for a group the store lacks, as `port.keyAudit ?? notPorted(port, 'keyAudit')`; it answers 501 as any unported path does. */
-export declare function notPorted(port: StorePort, group: keyof StoreGroups): never;
-/** Runs `run` on `ctx.store`, where a throw rejects, else on hippo.db under `ctx.hippoRoot`, where it throws. The store path never reads `hippoRoot`.
- *  `local` runs what needs hippo.db's own handle or meta table; a served store refuses it, or does without where the write allows. */
-export declare function onStore<C extends Context, R>(ctx: C, run: (port: StorePort, local: SqliteLocal) => Reply<R>): StoreReply<C, R>;
-//# sourceMappingURL=on-store.d.ts.map