hippo-memory 1.70.0 → 1.72.0

package/dist/server/server-detect.js

@@ -1,46 +1,38 @@
 import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
 import { envHealthProbeMs } from '../util/env.js';
-// Pidfile sits directly inside hippoRoot. `hippoRoot` is the `.hippo`
-// directory itself (the same convention used by api.ts / store.ts /
-// openHippoDb), so this resolves to `${hippoRoot}/server.pid`.
+import { errorCode, errorFields, errorMessage, log } from '../util/log.js';
+// Pidfile sits directly inside hippoRoot (the `.hippo` directory itself, as for openHippoDb), i.e. `${hippoRoot}/server.pid`.
 const PIDFILE = 'server.pid';
-/**
- * How long detectServer waits for the `/health` liveness probe before
- * treating the pidfile as stale. Short by design: the probe only fires on
- * the rare path where a pidfile exists and its pid is live, and the target
- * is always loopback, so a healthy server answers well within this bound. HIPPO_HEALTH_PROBE_MS overrides it.
- */
+/** How long detectServer waits for the `/health` probe before treating the pidfile as stale; short because it fires only when a pidfile exists with a live
+ * pid on loopback. HIPPO_HEALTH_PROBE_MS overrides it. */
 const HEALTH_PROBE_TIMEOUT_MS = 300;
-/**
- * Hard cap on the /health response body detectServer will buffer. A real
- * hippo /health payload is well under 1 KB; a larger body means the process
- * answering on the recorded port is not hippo, so the pidfile is stale.
- */
+/** Hard cap on the /health body detectServer buffers: a real payload is well under 1 KB, so a larger body means the process on the recorded port is not
+ * hippo. */
 const HEALTH_BODY_MAX_BYTES = 64 * 1024;
-/**
- * Loopback hosts the recorded pidfile url is allowed to point at. serve()
- * only binds these (it mirrors LOOPBACK_HOSTS in server.ts); a pidfile url
- * with any other host is malformed or forged and must not be probed.
- */
+/** Loopback hosts a recorded pidfile url may point at (serve() only binds these); any other host is malformed or forged and is not probed. */
 const PIDFILE_LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
+/** The pidfile names a live process on loopback that did not answer /health in time: most likely a busy server, so a caller must neither
+ * bypass it with a second writer nor start another server beside it. */
+export class ServerUnresponsiveError extends Error {
+    constructor(info, probeMs, options) {
+        super(`a hippo server (pid ${info.pid}) is recorded at ${info.url} but did not answer /health within ${probeMs} ms; it may be busy. ` +
+            'Retry shortly, raise HIPPO_HEALTH_PROBE_MS, or stop that server.', options);
+        this.name = 'ServerUnresponsiveError';
+    }
+}
 /** False when the pidfile's pid is dead or its url could not be one serve() wrote. */
 function isLiveLoopbackTarget(info) {
-    // Probe the process. Sending signal 0 throws if the pid is dead or owned
-    // by another user we cannot signal. Either way, treat as stale.
-    // Node's process.kill(pid, 0) is implemented on Windows via OpenProcess +
-    // GetExitCodeProcess, so this works cross-platform for the dead-pid case.
+    // Signal 0 throws if the pid is dead or owned by another user we cannot signal; either way, treat as stale.
+    // process.kill(pid, 0) works cross-platform for the dead-pid case (OpenProcess + GetExitCodeProcess on Windows).
     try {
         process.kill(info.pid, 0);
     }
     catch {
         return false;
     }
-    // The pid is live, but it may have been reused by an unrelated process, and
-    // the recorded url is read from a file anyone could forge. serve() only ever
-    // binds a loopback host, so a url that is not http on a loopback host and the
-    // recorded port is malformed or forged. Reject it before probing: the probe,
-    // and the routed request that may follow, can carry HIPPO_API_KEY.
+    // The pid may have been reused and the recorded url is read from a forgeable file; serve() only binds loopback, so a url that is not http on a loopback
+    // host and the recorded port is malformed or forged. Reject it before probing, since the probe and any routed request can carry HIPPO_API_KEY.
     let probeUrl;
     try {
         probeUrl = new URL(info.url);
@@ -54,9 +46,8 @@ function isLiveLoopbackTarget(info) {
 }
 /** The whole body as text, or null once it passes HEALTH_BODY_MAX_BYTES (the stream is then cancelled). */
 async function readCappedBody(body) {
-    // Read the body under a hard byte cap. The process answering on info.url
-    // may not be hippo (pid reuse is the case this probe guards against), so
-    // its response is untrusted: never hand an unbounded stream to a parser.
+    // Read the body under a hard byte cap: the process on info.url may not be hippo (pid reuse), so its response is untrusted and never goes unbounded into a
+    // parser.
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let raw = '';
@@ -75,18 +66,23 @@ async function readCappedBody(body) {
     raw += decoder.decode();
     return raw;
 }
-/** True when /health on info.url reports the pidfile's started_at; unlinks the pidfile on any definitive mismatch. */
+/** True when fetch failed because nothing listens on the port (the error or its cause, or any address tried, is ECONNREFUSED). */
+function isConnectionRefused(err) {
+    if (errorCode(err) === 'ECONNREFUSED')
+        return true;
+    const cause = err instanceof Error ? err.cause : undefined;
+    if (errorCode(cause) === 'ECONNREFUSED')
+        return true;
+    return cause instanceof AggregateError && cause.errors.length > 0 && cause.errors.every((e) => errorCode(e) === 'ECONNREFUSED');
+}
+/** True when /health on info.url reports the pidfile's started_at; unlinks the pidfile on any definitive mismatch and throws ServerUnresponsiveError on a
+ * probe timeout. */
 async function healthMatchesPidfile(hippoRoot, info) {
-    // Confirm the process answering on info.url is this hippo server by matching
-    // the /health `started_at` against the pidfile. A connection refusal, a
-    // non-200, or a malformed body unlink the pidfile as stale. A probe timeout
-    // is deliberately left ambiguous: a live but momentarily-busy server (e.g.
-    // blocked on a synchronous query) can miss the 300ms window, so a timeout
-    // returns null WITHOUT unlinking. The pidfile survives for the next probe.
+    // Refusal, non-200 or a malformed body unlink the pidfile as stale. A timeout proves neither a dead server nor this one, so it keeps the pidfile and throws.
+    // Any other error keeps it and warns.
+    const probeMs = envHealthProbeMs() ?? HEALTH_PROBE_TIMEOUT_MS;
     try {
-        const res = await fetch(`${info.url}/health`, {
-            signal: AbortSignal.timeout(envHealthProbeMs() ?? HEALTH_PROBE_TIMEOUT_MS),
-        });
+        const res = await fetch(`${info.url}/health`, { signal: AbortSignal.timeout(probeMs) });
         if (!res.ok || !res.body) {
             removePidfile(hippoRoot);
             return false;
@@ -104,32 +100,21 @@ async function healthMatchesPidfile(hippoRoot, info) {
         return true;
     }
     catch (err) {
-        // A timeout is ambiguous (the server may be alive but busy), so keep the
-        // pidfile. Any other failure (connection refused, malformed body) is
-        // definitive: unlink it as stale.
-        // SAFETY: err's shape is unknown (catch clause); reading an optional
-        // .name property structurally is safe regardless of the object's actual type.
-        if (err?.name !== 'TimeoutError') {
+        if (err instanceof Error && err.name === 'TimeoutError')
+            throw new ServerUnresponsiveError(info, probeMs, { cause: err });
+        // A refusal or a non-JSON body proves no hippo server answers there; any other failure may be a live server, so the file stays.
+        if (isConnectionRefused(err) || err instanceof SyntaxError) {
             removePidfile(hippoRoot);
         }
+        else {
+            log.warn(`server pidfile ${join(hippoRoot, PIDFILE)} kept: the /health probe failed (${errorMessage(err)})`, errorFields(err));
+        }
         return false;
     }
 }
-/**
- * Read .hippo/server.pid and return the embedded ServerInfo if a live hippo
- * server is genuinely answering on the recorded url. Returns null on missing,
- * malformed, or stale pidfiles, and best-effort unlinks the file in the
- * stale/malformed cases.
- *
- * Liveness is proven in two steps. `process.kill(pid, 0)` rules out dead
- * pids. But a pid can be reused by an unrelated process, so a GET /health
- * then confirms the process that answers is *this* hippo server: its
- * `started_at` must equal the pidfile's. A mismatch, non-200, malformed
- * body, or timeout all mean the pidfile is stale.
- *
- * The /health probe runs only when a pidfile exists and the pid is live, so
- * the common no-server path stays a single fast file existence check.
- */
+/** Returns the pidfile's ServerInfo if a live hippo server answers on the recorded url, else null (best-effort unlinking of missing/stale/malformed pidfiles).
+ * `process.kill(pid, 0)` rules out dead pids; GET /health must then return the pidfile's `started_at` (pids get reused). Probes only if the pid is live.
+ * Throws ServerUnresponsiveError when that probe times out. */
 export async function detectServer(hippoRoot) {
     const path = join(hippoRoot, PIDFILE);
     if (!existsSync(path))
@@ -138,7 +123,8 @@ export async function detectServer(hippoRoot) {
     try {
         info = JSON.parse(readFileSync(path, 'utf8'));
     }
-    catch {
+    catch (err) {
+        log.warn(`server pidfile ${path} is unreadable (${errorMessage(err)}); removing it`);
         removePidfile(hippoRoot);
         return null;
     }
@@ -148,14 +134,8 @@ export async function detectServer(hippoRoot) {
     }
     return (await healthMatchesPidfile(hippoRoot, info)) ? info : null;
 }
-/**
- * Atomically write the pidfile. Writes to a process-scoped temp file then
- * renames into place, which is atomic on POSIX and on NTFS via MoveFileEx.
- *
- * `startedAt` is supplied by the caller (`serve()`) rather than generated
- * here, so the pidfile and the server's GET /health response carry the same
- * timestamp — detectServer's liveness probe compares the two for equality.
- */
+/** Atomically writes the pidfile (process-scoped temp file, then rename; atomic on POSIX and NTFS). `startedAt` comes from the caller (`serve()`) so the
+ * pidfile and GET /health carry the same timestamp, which detectServer's liveness probe compares. */
 export function writePidfile(hippoRoot, opts) {
     const path = join(hippoRoot, PIDFILE);
     const tmp = `${path}.tmp.${process.pid}`;
@@ -169,13 +149,8 @@ export function writePidfile(hippoRoot, opts) {
     writeFileSync(tmp, JSON.stringify(info));
     renameSync(tmp, path);
 }
-/**
- * Best-effort pidfile removal. Silent on ENOENT or any other error so the
- * caller can use this in shutdown paths without fear of throwing.
- *
- * Identity-blind: deletes whatever pidfile is on disk. A shutdown path that
- * must not clobber a newer server's pidfile should use removePidfileIfOwned.
- */
+/** Best-effort pidfile removal, silent on any error so shutdown paths can call it. Identity-blind: a shutdown that must not clobber a newer server's pidfile
+ * uses removePidfileIfOwned. */
 export function removePidfile(hippoRoot) {
     const path = join(hippoRoot, PIDFILE);
     try {
@@ -183,24 +158,8 @@ export function removePidfile(hippoRoot) {
     }
     catch { /* already gone or undeletable; the next detectServer probe re-checks */ }
 }
-/**
- * Remove the pidfile only if it still describes the caller's own server.
- * Reads and parses the pidfile and unlinks it ONLY when both `pid` and
- * `started_at` match `owner`. A pidfile rewritten by a newer server is left
- * intact, so a shutting-down older server cannot orphan the newer one by
- * deleting its pidfile out from under it.
- *
- * Best-effort and never throws: a missing, unreadable, malformed, or
- * non-object pidfile (including a literal JSON `null`) is "not provably mine"
- * and left alone — detectServer unlinks a malformed pidfile on its next
- * probe, so it does not leak. Returns true iff a matching pidfile was removed.
- *
- * Residual TOCTOU: the pidfile could be rewritten between the read and the
- * unlink. The window is microseconds and the shape is the same read-check-
- * unlink detectServer already uses; this narrows the clobber from an
- * unbounded window (any time between writePidfile and stop) to a negligible
- * one.
- */
+/** Removes the pidfile ONLY when both `pid` and `started_at` match `owner`, so an older shutting-down server cannot orphan a newer one; never throws.
+ * Anything unreadable or malformed is "not provably mine" and left alone (detectServer unlinks it). Returns true iff removed. */
 export function removePidfileIfOwned(hippoRoot, owner) {
     const path = join(hippoRoot, PIDFILE);
     try {

package/dist/server/sleep-child.js

@@ -1,19 +1,38 @@
-// Entry of the process that runs one POST /v1/sleep; sleep-offload.ts starts it and nothing imports it.
-// The sleep module alone: the api barrel loads far more than one sleep needs, and every sleep pays for the start.
+// Entry of the process that runs one POST /v1/sleep or MCP auto-sleep; sleep-offload.ts starts it and nothing imports it.
+// The sleep modules alone: the api barrel loads far more than one sleep needs, and every sleep pays for the start.
 import { sleep } from '../api/sleep.js';
-import { isStoreBusy, runWithRequestStores, SERVER_DB_WAIT_MS } from '../db/index.js';
-import { errorMessage } from '../util/log.js';
+import { consolidate } from '../consolidate/sleep.js';
+import { runWithRequestStores, SERVER_DB_WAIT_MS } from '../db/index.js';
+import { isStoreBusy } from '../store/sqlite/busy.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 function failed(err) {
     return { ok: false, busy: isStoreBusy(err), message: errorMessage(err), stack: err instanceof Error ? err.stack : undefined };
 }
+/** Resolves to the exit code once the channel has taken the reply, or failed to. */
+function sendReply(reply) {
+    return new Promise((resolve) => {
+        process.send?.(reply, (sendErr) => {
+            if (sendErr)
+                log.error(`sleep child: sending the reply failed: ${errorMessage(sendErr)}`, errorFields(sendErr));
+            resolve(sendErr ? 1 : 0);
+        });
+    });
+}
 process.once('message', (message) => {
     // SAFETY: sleep-offload.ts is the only writer on this channel and sends exactly one SleepJob.
     const job = message;
-    const ctx = { hippoRoot: job.hippoRoot, tenantId: job.tenantId, actor: job.actor };
+    const work = () => job.kind === 'consolidate'
+        ? consolidate(job.hippoRoot)
+        : sleep({ hippoRoot: job.hippoRoot, tenantId: job.tenantId, actor: job.actor }, job.opts);
     // The server's own request scope and lock wait, so a busy store answers as it did when sleep ran in the server.
-    runWithRequestStores(() => sleep(ctx, job.opts), { busyWaitMs: SERVER_DB_WAIT_MS })
+    runWithRequestStores(work, { busyWaitMs: SERVER_DB_WAIT_MS })
         .then((result) => ({ ok: true, result }), failed)
         // Exit only once the reply is written, or the parent could see the process end first.
-        .then((reply) => process.send?.(reply, () => process.exit(0)));
+        .then(sendReply)
+        .catch((err) => {
+        log.error(`sleep child: the reply could not be sent: ${errorMessage(err)}`, errorFields(err));
+        return 1;
+    })
+        .then((code) => process.exit(code));
 });
 //# sourceMappingURL=sleep-child.js.map

package/dist/server/sleep-offload.d.ts

@@ -1,14 +1,18 @@
 import { type Actor, type Context, type SleepOpts, type SleepResult } from '../api/index.js';
-/** What the child needs to rebuild the request's context; the store handle itself cannot cross a process boundary. */
-export interface SleepJob {
+/** What the child needs to rebuild the request's context (the store handle itself cannot cross a process boundary), or the store an auto-sleep consolidates. */
+export type SleepJob = {
+    readonly kind: 'sleep';
     readonly hippoRoot: string;
     readonly tenantId: string;
     readonly actor: Actor;
     readonly opts: SleepOpts;
-}
-export type SleepReply = {
+} | {
+    readonly kind: 'consolidate';
+    readonly hippoRoot: string;
+};
+export type SleepReply<R = SleepResult> = {
     readonly ok: true;
-    readonly result: SleepResult;
+    readonly result: R;
 } | {
     readonly ok: false;
     readonly busy: boolean;
@@ -17,4 +21,6 @@ export type SleepReply = {
 };
 /** `sleep` for the HTTP route: same result and errors, run outside the serving process and stopped at the deadline (10 minutes, or HIPPO_SLEEP_TIMEOUT_MS). */
 export declare function sleepInChild(ctx: Context, opts: SleepOpts): Promise<SleepResult>;
+/** The MCP auto-sleep's consolidation, in the same queue and child as POST /v1/sleep; auto-sleep only starts on a hippo.db store. */
+export declare function consolidateInChild(hippoRoot: string): Promise<void>;
 //# sourceMappingURL=sleep-offload.d.ts.map

package/dist/server/sleep-offload.js

@@ -1,8 +1,8 @@
-// POST /v1/sleep runs its consolidation in a child process, so the server keeps answering and a stuck run can be stopped.
+// POST /v1/sleep and the MCP auto-sleep run their consolidation in a child process, so the server keeps answering and a stuck run can be stopped.
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { sleep } from '../api/index.js';
-import { StoreBusyError } from '../db/index.js';
+import { StoreBusyError } from '../store/port.js';
 import { envSleepTimeoutMs } from '../util/env.js';
 import { HttpError } from '../util/http-util.js';
 const DEFAULT_SLEEP_DEADLINE_MS = 600_000;
@@ -23,13 +23,16 @@ function runInChild(job) {
     const deadlineMs = envSleepTimeoutMs() ?? DEFAULT_SLEEP_DEADLINE_MS;
     return new Promise((resolve, reject) => {
         // The child's stderr is the server's log, so Node's SQLite notice would repeat there on every sleep.
-        const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', CHILD_ENTRY], { stdio: ['ignore', 'inherit', 'inherit', 'ipc'], windowsHide: true });
+        const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', CHILD_ENTRY], {
+            stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+            windowsHide: true
+        });
         let reply;
         let timedOut = false;
         // SIGKILL because the child is inside synchronous SQLite work and cannot run a handler; the OS drops its write lock.
         const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, deadlineMs);
         child.once('message', (message) => {
-            // SAFETY: sleep-child.ts is the only writer on this channel and sends exactly one SleepReply.
+            // SAFETY: sleep-child.ts is the only writer on this channel and sends exactly one SleepReply for the job it was given.
             reply = message;
         });
         child.once('error', (err) => { clearTimeout(timer); reject(err); });
@@ -51,20 +54,26 @@ let turn = Promise.resolve();
 const MAX_SLEEPS_IN_LINE = 2;
 const SLEEP_RETRY_AFTER_SEC = 30;
 let inLine = 0;
-/** `sleep` for the HTTP route: same result and errors, run outside the serving process and stopped at the deadline (10 minutes, or HIPPO_SLEEP_TIMEOUT_MS). */
-export function sleepInChild(ctx, opts) {
-    // The child reopens the store by path, which only SQLite has; any other store keeps sleep's own refusal.
-    if (ctx.store && ctx.store.kind !== 'sqlite')
-        return sleep(ctx, opts);
+function inTurn(job) {
     if (inLine >= MAX_SLEEPS_IN_LINE) {
         return Promise.reject(new HttpError(503, 'a sleep is already running and another is waiting; retry when one has finished', SLEEP_RETRY_AFTER_SEC));
     }
     inLine += 1;
-    const job = { hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor, opts };
-    // One sleep at a time, as on the server's single thread: a second request waits its turn and does not fight the first for the write lock.
+    // One sleep at a time, as on the server's single thread: a second one waits its turn and does not fight the first for the write lock.
     const run = turn.then(() => runInChild(job));
-    // A failed sleep reaches its own request through `run`; the queue only needs to know the turn is over.
+    // A failed sleep reaches its own caller through `run`; the queue only needs to know the turn is over.
     turn = run.then(() => undefined, () => undefined).finally(() => { inLine -= 1; });
     return run;
 }
+/** `sleep` for the HTTP route: same result and errors, run outside the serving process and stopped at the deadline (10 minutes, or HIPPO_SLEEP_TIMEOUT_MS). */
+export function sleepInChild(ctx, opts) {
+    // The child reopens the store by path, which only SQLite has; any other store keeps sleep's own refusal.
+    if (ctx.store && ctx.store.kind !== 'sqlite')
+        return sleep(ctx, opts);
+    return inTurn({ kind: 'sleep', hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor, opts });
+}
+/** The MCP auto-sleep's consolidation, in the same queue and child as POST /v1/sleep; auto-sleep only starts on a hippo.db store. */
+export async function consolidateInChild(hippoRoot) {
+    await inTurn({ kind: 'consolidate', hippoRoot });
+}
 //# sourceMappingURL=sleep-offload.js.map

package/dist/server/types.d.ts

@@ -7,17 +7,16 @@ export interface ServerHandle {
     port: number;
     url: string;
     stop: () => Promise<void>;
-    /** Introspection-only: the underlying node:http Server, exposed so
-     *  tests can assert keep-alive/headers timeout hardening without reaching
-     *  into serve()'s closure. Additive field — do not depend on it for control
-     *  flow outside tests. */
+    /** Introspection-only: the underlying node:http Server, so tests can assert keep-alive/headers timeout hardening without reaching into serve()'s closure.
+     * Do not use for control flow. */
     server?: import('node:http').Server;
 }
 /** Identity an {@link AuthResolver} vouches for. The core sanitises it before use. */
 export interface ResolvedBearer {
     tenantId: string;
     subject: string;
-    /** Not 'admin' means 'member'. Admin is tenant-only, yet can mint member API keys (POST /v1/auth/keys); an add-on revokes them through the exported authRevoke when the IdP deprovisions the minter. */
+    /** Not 'admin' means 'member'. Admin is tenant-only, yet can mint member API keys (POST /v1/auth/keys);
+     * an add-on revokes them through the exported authRevoke when the IdP deprovisions the minter. */
     role: 'admin' | 'member';
     scopes?: readonly string[];
 }
@@ -28,7 +27,8 @@ export interface AddonCall {
     readonly ctx: Context;
     readonly body: Readonly<Record<string, JsonValue>>;
 }
-/** A POST /v1 route an add-on mounts through serve(): core authenticates and parses first, then sends the returned value as 200 JSON. Under another store it runs only when that store has its `storeReady` group. */
+/** A POST /v1 route an add-on mounts through serve(): core authenticates and parses first, then sends the
+ * returned value as 200 JSON. Under another store it runs only when that store has its `storeReady` group. */
 export interface AddonRoute {
     readonly path: string;
     readonly handler: (call: AddonCall) => Promise<JsonValue>;
@@ -46,7 +46,8 @@ export interface ServeOpts {
     authResolverTimeoutMs?: number;
     port?: number;
     host?: string;
-    /** Stop and exit on SIGINT/SIGTERM, and drain then exit 1 on an uncaught exception or unhandled rejection. Only `hippo serve` owns the process, so only it sets this. */
+    /** Stop and exit on SIGINT/SIGTERM, and drain then exit 1 on an uncaught exception or unhandled rejection. A stop still running
+     * 10 s past `shutdownDrainMs` ends the process with a failure exit. Only `hippo serve` owns the process, so only it sets this. */
     handleSignals?: boolean;
     /** How long stop() lets in-flight requests finish before closing their sockets; defaults to 5000 ms. */
     shutdownDrainMs?: number;
@@ -59,7 +60,8 @@ export interface ServeOpts {
     mintBodyDeadlineMs?: number;
     /** Tests only: shortens the wait for a signed webhook's body, which defaults to 10 s. */
     webhookBodyDeadlineMs?: number;
-    /** PEM certificate and key: serve() then answers HTTPS only. Unset means cleartext HTTP, which needs a TLS-terminating proxy in front on any non-loopback bind. */
+    /** PEM certificate and key: serve() then answers HTTPS only. Unset means cleartext
+     * HTTP, which needs a TLS-terminating proxy in front on any non-loopback bind. */
     tls?: {
         cert: string | Buffer;
         key: string | Buffer;
@@ -86,6 +88,10 @@ export interface RouteRequest {
     opts: ResolvedServeOpts;
     query: URLSearchParams;
 }
+/** A request past the dispatch gate, carrying the caller the gate authenticated. */
+export interface AuthedRouteRequest extends RouteRequest {
+    ctx: Context;
+}
 /** A route's store status: a `storeReady` group, a `sqliteOnly` reason, or neither while it waits for a group; never both. */
 type StoreStatus = {
     storeReady?: StoreGroup;
@@ -94,20 +100,28 @@ type StoreStatus = {
     sqliteOnly: string;
     storeReady?: never;
 };
-/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with the handler for one method. Under another store it runs only when that store has its `storeReady` group; a `sqliteOnly` route never does.
- *  `loop: 'off'` declares that the route's SQLite work runs on a worker thread, so its handler opens no hippo.db on the server thread. */
-export type Route = {
-    method: string;
-    loop?: 'off';
-} & StoreStatus & ({
+/** What the dispatch gate proves before a handler runs: any caller, an admin, a host admin on loopback, or nothing, for a route
+ * whose handler checks the sender's signature itself. */
+export type RouteAuth = 'caller' | 'admin' | 'host-admin-local' | 'webhook-signature';
+export type RouteEndpoint<R> = {
     path: string;
-    handler: (r: RouteRequest) => Promise<void>;
+    handler: (r: R) => Promise<void>;
 } | {
     pattern: string;
-    handler: (r: RouteRequest, params: Record<string, string>) => Promise<void>;
+    handler: (r: R, params: Record<string, string>) => Promise<void>;
 } | {
     regex: RegExp;
-    handler: (r: RouteRequest, match: RegExpMatchArray) => Promise<void>;
-});
+    handler: (r: R, match: RegExpMatchArray) => Promise<void>;
+};
+/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with one method's handler. Under another store it runs only with its
+ * store's `storeReady` group; `loop: 'off'` runs its SQLite work on a worker thread, so the handler opens no hippo.db on the server thread. */
+export type Route = {
+    method: string;
+    loop?: 'off';
+} & StoreStatus & (({
+    auth: Exclude<RouteAuth, 'webhook-signature'>;
+} & RouteEndpoint<AuthedRouteRequest>) | ({
+    auth: 'webhook-signature';
+} & RouteEndpoint<RouteRequest>));
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/server/validation.d.ts

@@ -2,9 +2,10 @@ import type { IncomingMessage } from 'node:http';
 import type { Context, RememberOpts } from '../api/index.js';
 import { type JsonValue } from '../util/json.js';
 export declare function isSetMember<T extends string>(set: ReadonlySet<T>, value: string): value is T;
-export declare const MAX_LIST_LIMIT = 1000;
+export declare const MAX_SHORT_FIELD_LEN = 4096;
 export declare function parseListLimit(limitRaw: string | null, defaultLimit?: number, maxLimit?: number): number;
-/** `_authed` is proof the caller passed auth, so a full-size body is read only for an authenticated caller; the key mint reads first under its own small cap. */
+/** `_authed` is proof the caller passed auth, so a full-size body is read only for
+ * an authenticated caller; the key mint reads under its own small cap. */
 export declare function parseJsonBody(req: IncomingMessage, _authed: Context): Promise<Record<string, JsonValue>>;
 export declare function parseJsonObjectText(raw: string): Record<string, JsonValue>;
 export declare function getString(obj: Record<string, JsonValue>, key: string): string | undefined;

package/dist/server/validation.js

@@ -1,31 +1,22 @@
-import { HttpError, MAX_ID_LEN, readBody } from '../util/http-util.js';
+import { HttpError, readBody } from '../util/http-util.js';
+import { DEFAULT_LIST_LIMIT, MAX_ID_LEN, MAX_LIST_LIMIT, resolveListLimit } from '../util/limits.js';
 import { isJsonString, isJsonObject } from '../util/json.js';
-// Runtime membership check for a `ReadonlySet<T>` of string-literal union
-// members, used at every `body` field validated against a VALID_* set below.
-// Set<T>.has(value: T) itself gives no narrowing (its parameter type is T,
-// not a type predicate) so callers previously needed a separate `as T` cast
-// at both the check and the later usage; this helper is the one place that
-// assertion lives, so downstream call sites narrow via the `value is T`
-// return instead of re-asserting.
+// Runtime membership check for a `ReadonlySet<T>` of string-literal members: Set<T>.has gives no narrowing, so this is the one place the `as T` assertion lives
+// and callers narrow via the `value is T` return.
 export function isSetMember(set, value) {
-    // SAFETY: `value as T` is discarded unless `set.has` (the real runtime
-    // check) confirms membership; the `value is T` return type is what
-    // performs the actual narrowing for callers.
+    // SAFETY: `value as T` is discarded unless `set.has` (the real runtime check) confirms membership; the `value is T` return type does the narrowing.
     return set.has(value);
 }
-// Number.isInteger, not isFinite: SQLite `LIMIT ?` rejects "1.5" with a 500.
-// Shared by every first-class-object list route so the guard cannot drift.
-export const MAX_LIST_LIMIT = 1000;
-export function parseListLimit(limitRaw, defaultLimit = 100, maxLimit = MAX_LIST_LIMIT) {
-    if (limitRaw === null)
-        return defaultLimit;
-    const limit = Number(limitRaw);
-    if (!Number.isInteger(limit) || limit <= 0 || limit > maxLimit) {
+// Cap for short free-text HTTP fields (names, text, context, change summaries) on the object routes.
+export const MAX_SHORT_FIELD_LEN = 4096;
+export function parseListLimit(limitRaw, defaultLimit = DEFAULT_LIST_LIMIT, maxLimit = MAX_LIST_LIMIT) {
+    const limit = resolveListLimit(limitRaw === null ? undefined : Number(limitRaw), defaultLimit, maxLimit);
+    if (limit === undefined)
         throw new HttpError(400, `limit must be a positive integer <= ${maxLimit}`);
-    }
     return limit;
 }
-/** `_authed` is proof the caller passed auth, so a full-size body is read only for an authenticated caller; the key mint reads first under its own small cap. */
+/** `_authed` is proof the caller passed auth, so a full-size body is read only for
+ * an authenticated caller; the key mint reads under its own small cap. */
 export async function parseJsonBody(req, _authed) {
     return parseJsonObjectText(await readBody(req));
 }
@@ -72,18 +63,9 @@ export function getCallerProject(body) {
     }
     return { name: v.name, aliases: v.aliases };
 }
-/**
- * Charset + length validation for `:id` route captures. Routes call
- * this immediately after `matchPath` to reject empty / overlong / illegal
- * ids with a useful 400 instead of silently falling through to "not found".
- *
- * Allowed charset matches all production id shapes Hippo emits: `mem_<hex>`,
- * `sum_<hex>`, `sess-<id>`, Slack bot ids like `B01ABCD`, etc. The `:` and
- * `.` are allowed for forward-compat. The `/` is intentionally absent —
- * Hippo never emits ids with slashes, and `rejectEncodedSlash` already
- * stops `%2F`-smuggled ones at the front door.
- */
-const ID_SEGMENT_RE = /^[A-Za-z0-9_:.\-]+$/;
+/** Charset + length validation for `:id` captures, called right after `matchPath` so empty/overlong/illegal ids get a 400, not "not found".
+ * Allows every production id shape (`mem_<hex>`, `sess-<id>`, Slack ids) plus `:` and `.`; no `/`, since `rejectEncodedSlash` stops `%2F` smuggling. */
+const ID_SEGMENT_RE = /^[A-Za-z0-9_:.-]+$/;
 export function validateIdSegment(id, fieldName) {
     if (id.length === 0)
         throw new HttpError(400, `${fieldName} is required`);

package/dist/server.d.ts

@@ -13,8 +13,9 @@ export type { JsonValue } from './util/json.js';
 export { captureSessionTexts, type SessionCaptureRequest, type SessionCaptureResult } from './capture/session-texts.js';
 export { hasGroup, sqliteStore, type AmbientCandidateRequest, type ContextReads, type EntryRemoval, type EntryTarget, type EntryWrite, type EntryWrites, type HippoStore, type KeyAudit, type KeyListQuery, type KeyMint, type KeyRevoke, type KeyWrites, type OutcomeWrite, type RawArchive, type RecallSearchArgs, type RecallWrites, type SelfKeyMint, type StoreGroup, type StoreGroups, type SupersedeWrite, type VectorReads, type VectorBackfillQuery, type VectorRowWrite, type VectorWrite, type VectorWriteResult, type VectorWrites, } from './store/index.js';
 export { entryAfterOutcome } from './core/memory.js';
-export { rejectionDigest, RejectedValueError } from './store/rejection.js';
-export { ownScopeTouches } from './store/recall-scope.js';
+export { rejectionDigest } from './store/rejection.js';
+export { RejectedValueError } from './core/api-errors.js';
+export { ownScopeTouches } from './core/recall-scope.js';
 export { BadRequestError, ConflictError } from './core/api-errors.js';
 export type { HippoDbContext, StoreReply } from './api/types.js';
 export type { ApiKeyListItem, ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './store/auth.js';
@@ -35,13 +36,13 @@ export type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, R
 export type { AmbientStoreFilter } from './store/ambient.js';
 export type { AmbientTallies } from './core/ambient.js';
 export type { TokenUse } from './store/token-ledger.js';
-export type { EmbeddingIndexState } from './store/embeddings/index.js';
+export type { EmbeddingIndexState } from './store/vector-index.js';
 export type { PhysicsParticle } from './core/physics.js';
-export { StoreBusyError } from './db/index.js';
+export { StoreBusyError } from './store/port.js';
 export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows, type VectorMatch, type VectorRow } from './db/vector-store.js';
 export { bufferToFloat32, float32ToBuffer } from './db/physics-state.js';
-export { replacesIndex } from './store/embeddings/index.js';
-export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './store/recall-scope.js';
+export { replacesIndex } from './store/vector-index.js';
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './core/recall-scope.js';
 export { SECRET_TAGS } from './util/secret-detect.js';
 export { tallyAmbientEntries } from './core/ambient.js';
 export { ftsTermParts, rarestFtsQuery } from './core/prompt-recall.js';

package/dist/server.js

@@ -9,7 +9,8 @@ export { isCrossSite, LOOPBACK_HOST_HEADER } from './util/http-util.js';
 export { __resetSessionRecallHistoryHttp } from './server/routes/recall.js';
 export { clientIpForRateLimit } from './server/client-ip.js';
 export { isLoopback, isReservedActor } from './server/auth.js';
-// What an add-on route handler needs: HttpError for its 4xx replies, promptHookContext for a caller that renders the prompt hook elsewhere, JsonValue for its body.
+// What an add-on route handler needs: HttpError for its 4xx replies, promptHookContext
+// for a caller that renders the prompt hook elsewhere, JsonValue for its body.
 export { HttpError } from './util/http-util.js';
 export { promptHookContext } from './api/prompt-hook.js';
 // A session-end route stores the turns its caller read from a transcript on the caller's own machine.
@@ -18,17 +19,18 @@ export { captureSessionTexts } from './capture/session-texts.js';
 export { hasGroup, sqliteStore, } from './store/index.js';
 // An add-on store's entry writes apply an outcome, guard tombstones and check reach exactly as hippo.db does.
 export { entryAfterOutcome } from './core/memory.js';
-export { rejectionDigest, RejectedValueError } from './store/rejection.js';
-export { ownScopeTouches } from './store/recall-scope.js';
+export { rejectionDigest } from './store/rejection.js';
+export { RejectedValueError } from './core/api-errors.js';
+export { ownScopeTouches } from './core/recall-scope.js';
 export { BadRequestError, ConflictError } from './core/api-errors.js';
-export { StoreBusyError } from './db/index.js';
+export { StoreBusyError } from './store/port.js';
 // An add-on store encodes, decodes and ranks vectors and particles with hippo.db's own code, and drops the index by its rule,
 // so both stores keep the same bytes and return the same ids in the same order.
 export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows } from './db/vector-store.js';
 export { bufferToFloat32, float32ToBuffer } from './db/physics-state.js';
-export { replacesIndex } from './store/embeddings/index.js';
+export { replacesIndex } from './store/vector-index.js';
 // An add-on's ContextReads applies hippo.db's scope, secret, tally and rarest-term rules with the same code.
-export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './store/recall-scope.js';
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './core/recall-scope.js';
 export { SECRET_TAGS } from './util/secret-detect.js';
 export { tallyAmbientEntries } from './core/ambient.js';
 export { ftsTermParts, rarestFtsQuery } from './core/prompt-recall.js';