hippo-memory 1.69.0 → 1.71.0

package/dist/server/server-detect.js

@@ -0,0 +1,156 @@
+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 (the `.hippo` directory itself, as for openHippoDb), i.e. `${hippoRoot}/server.pid`.
+const PIDFILE = 'server.pid';
+/** 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 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 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']);
+/** False when the pidfile's pid is dead or its url could not be one serve() wrote. */
+function isLiveLoopbackTarget(info) {
+    // 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 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);
+    }
+    catch {
+        return false;
+    }
+    return (probeUrl.protocol === 'http:' &&
+        PIDFILE_LOOPBACK_HOSTS.has(probeUrl.hostname.replace(/^\[(.*)\]$/, '$1')) &&
+        probeUrl.port === String(info.port));
+}
+/** 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 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 = '';
+    let received = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > HEALTH_BODY_MAX_BYTES) {
+            await reader.cancel();
+            return null;
+        }
+        raw += decoder.decode(value, { stream: true });
+    }
+    raw += decoder.decode();
+    return raw;
+}
+/** True when /health on info.url reports the pidfile's started_at; unlinks the pidfile on any definitive mismatch. */
+async function healthMatchesPidfile(hippoRoot, info) {
+    // Confirm the answering process is this server by matching /health `started_at` against the pidfile; refusal, non-200 or a malformed body unlink the
+    // pidfile as stale. A probe timeout is ambiguous (a live but busy server can miss the 300ms window), so it returns null WITHOUT unlinking.
+    try {
+        const res = await fetch(`${info.url}/health`, {
+            signal: AbortSignal.timeout(envHealthProbeMs() ?? HEALTH_PROBE_TIMEOUT_MS),
+        });
+        if (!res.ok || !res.body) {
+            removePidfile(hippoRoot);
+            return false;
+        }
+        const raw = await readCappedBody(res.body);
+        if (raw === null) {
+            removePidfile(hippoRoot);
+            return false;
+        }
+        const body = JSON.parse(raw);
+        if (body.started_at !== info.started_at) {
+            removePidfile(hippoRoot);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        // A timeout is ambiguous (the server may be busy), so keep the pidfile; any other failure (refused, malformed body) is definitive: unlink as stale.
+        // SAFETY: err's shape is unknown (catch clause); reading an optional .name property structurally is safe regardless of the actual type.
+        if (err?.name !== 'TimeoutError') {
+            removePidfile(hippoRoot);
+        }
+        return false;
+    }
+}
+/** 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. */
+export async function detectServer(hippoRoot) {
+    const path = join(hippoRoot, PIDFILE);
+    if (!existsSync(path))
+        return null;
+    let info;
+    try {
+        info = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        removePidfile(hippoRoot);
+        return null;
+    }
+    if (!isLiveLoopbackTarget(info)) {
+        removePidfile(hippoRoot);
+        return null;
+    }
+    return (await healthMatchesPidfile(hippoRoot, info)) ? info : null;
+}
+/** 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}`;
+    const info = {
+        schema: 1,
+        pid: process.pid,
+        port: opts.port,
+        url: opts.url,
+        started_at: opts.startedAt,
+    };
+    writeFileSync(tmp, JSON.stringify(info));
+    renameSync(tmp, path);
+}
+/** 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 {
+        unlinkSync(path);
+    }
+    catch { /* already gone or undeletable; the next detectServer probe re-checks */ }
+}
+/** 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 {
+        const info = JSON.parse(readFileSync(path, 'utf8'));
+        // A literal JSON `null` parses cleanly but throws on property access;
+        // that lands in the catch below, which is the intended "not mine" path.
+        if (info.pid !== owner.pid || info.started_at !== owner.startedAt) {
+            return false; // a different server owns the pidfile now
+        }
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        // Missing, unreadable, malformed, or non-object pidfile, or an unlink
+        // failure: none is a provable own-removal, so report not-removed.
+        return false;
+    }
+}
+//# sourceMappingURL=server-detect.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sleep-child.d.ts.map

package/dist/server/sleep-child.js

@@ -0,0 +1,19 @@
+// 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.
+import { sleep } from '../api/sleep.js';
+import { isStoreBusy, runWithRequestStores, SERVER_DB_WAIT_MS } from '../db/index.js';
+import { errorMessage } from '../util/log.js';
+function failed(err) {
+    return { ok: false, busy: isStoreBusy(err), message: errorMessage(err), stack: err instanceof Error ? err.stack : undefined };
+}
+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 };
+    // 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 })
+        .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)));
+});
+//# sourceMappingURL=sleep-child.js.map

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

@@ -0,0 +1,20 @@
+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 {
+    readonly hippoRoot: string;
+    readonly tenantId: string;
+    readonly actor: Actor;
+    readonly opts: SleepOpts;
+}
+export type SleepReply = {
+    readonly ok: true;
+    readonly result: SleepResult;
+} | {
+    readonly ok: false;
+    readonly busy: boolean;
+    readonly message: string;
+    readonly stack?: string;
+};
+/** `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>;
+//# sourceMappingURL=sleep-offload.d.ts.map

package/dist/server/sleep-offload.js

@@ -0,0 +1,73 @@
+// POST /v1/sleep runs its 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 { envSleepTimeoutMs } from '../util/env.js';
+import { HttpError } from '../util/http-util.js';
+const DEFAULT_SLEEP_DEADLINE_MS = 600_000;
+// Resolved from the package root, so a server run from TypeScript source starts the same built file.
+const CHILD_ENTRY = fileURLToPath(new URL('../../dist/server/sleep-child.js', import.meta.url));
+function failureOf(reply, code, signal) {
+    if (!reply || reply.ok)
+        return new Error(`sleep process ended without an answer (code ${code}, signal ${signal})`);
+    // A lock the child could not get is the same retryable 503 an in-process sleep gave.
+    if (reply.busy)
+        return new StoreBusyError(reply.message);
+    const failure = new Error(reply.message);
+    if (reply.stack)
+        failure.stack = reply.stack;
+    return failure;
+}
+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
+        });
+        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.
+            reply = message;
+        });
+        child.once('error', (err) => { clearTimeout(timer); reject(err); });
+        // 'close' and not 'exit': it waits for the channel to drain, so the reply is in hand and the child's store handles are gone.
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            if (timedOut)
+                reject(new HttpError(504, `sleep did not finish within ${deadlineMs} ms and was stopped; the next sleep carries on from there`));
+            else if (reply?.ok)
+                resolve(reply.result);
+            else
+                reject(failureOf(reply, code, signal));
+        });
+        child.send(job);
+    });
+}
+let turn = Promise.resolve();
+// One running and one waiting: each further sleep would only hold a request open behind work the waiting one already covers.
+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);
+    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.
+    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.
+    turn = run.then(() => undefined, () => undefined).finally(() => { inLine -= 1; });
+    return run;
+}
+//# sourceMappingURL=sleep-offload.js.map

package/dist/server/tls.d.ts

@@ -0,0 +1,6 @@
+import { type RequestListener, type Server } from 'node:http';
+import type { ServeOpts } from './types.js';
+export declare function createListener(tls: ServeOpts['tls'], onRequest: RequestListener): Server;
+/** Said once at boot: a non-loopback bind without TLS sends every key and memory over the network as plain text. */
+export declare function warnIfCleartext(host: string, tls: ServeOpts['tls'], loopbackHosts: ReadonlySet<string>): void;
+//# sourceMappingURL=tls.d.ts.map

package/dist/server/tls.js

@@ -0,0 +1,24 @@
+// The serve() listener: node:https when a certificate is given, else node:http and a boot warning off loopback.
+import { createServer as createHttpServer } from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import { errorMessage, log } from '../util/log.js';
+export function createListener(tls, onRequest) {
+    if (!tls)
+        return createHttpServer(onRequest);
+    try {
+        // Explicit so the floor does not move with the runtime's default.
+        return createHttpsServer({ cert: tls.cert, key: tls.key, minVersion: 'TLSv1.2' }, onRequest);
+    }
+    catch (err) {
+        // OpenSSL's own text names no file, so the operator would not know which input was refused.
+        throw new Error(`hippo serve: the TLS certificate or key was refused: ${errorMessage(err)}`, { cause: err });
+    }
+}
+/** Said once at boot: a non-loopback bind without TLS sends every key and memory over the network as plain text. */
+export function warnIfCleartext(host, tls, loopbackHosts) {
+    if (tls || loopbackHosts.has(host))
+        return;
+    log.warn(`serve: listening on ${host} without TLS, so API keys and memory text travel in cleartext unless a TLS-terminating proxy sits in front. ` +
+        'To serve HTTPS directly, pass --tls-cert and --tls-key (or set HIPPO_TLS_CERT and HIPPO_TLS_KEY).');
+}
+//# sourceMappingURL=tls.js.map

package/dist/server/types.d.ts

@@ -1,23 +1,22 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { Context } from '../api.js';
-import type { JsonValue } from '../json.js';
-import type { RateLimiter } from '../rate-limit.js';
-import type { HippoStore, StoreGroup } from '../store-port.js';
+import type { Context } from '../api/index.js';
+import type { JsonValue } from '../util/json.js';
+import type { RateLimiter } from './rate-limit.js';
+import type { HippoStore, StoreGroup } from '../store/index.js';
 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,15 +46,26 @@ export interface ServeOpts {
     authResolverTimeoutMs?: number;
     port?: number;
     host?: string;
-    /** Stop and exit on SIGINT/SIGTERM. 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;
+    /** How long a request may stay unanswered before one warn names it; the request itself is left alone. Defaults to 60000 ms. */
+    slowRequestWarnMs?: number;
     /** Defaults to hippo.db under `hippoRoot`. A store of another kind runs only the routes ported to it; its caller closes it. */
     store?: HippoStore;
     autoSleep?: false;
     routes?: readonly AddonRoute[];
     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. */
+    tls?: {
+        cert: string | Buffer;
+        key: string | Buffer;
+    };
     /** Static JSON served to anyone at GET <path>; built once at boot and never authenticated, so it must hold nothing secret. */
     publicJson?: Readonly<Record<string, JsonValue>>;
     /** Request limits: perCaller after auth; perAddress replaces HIPPO_V1_RPS when set, 'off' disables it; failedAuthPerAddress guards scrypt. */
@@ -77,11 +88,20 @@ export interface RouteRequest {
     opts: ResolvedServeOpts;
     query: URLSearchParams;
 }
-/** 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 route's store status: a `storeReady` group, a `sqliteOnly` reason, or neither while it waits for a group; never both. */
+type StoreStatus = {
+    storeReady?: StoreGroup;
+    sqliteOnly?: never;
+} | {
+    sqliteOnly: string;
+    storeReady?: never;
+};
+/** 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;
-    storeReady?: StoreGroup;
-} & ({
+    loop?: 'off';
+} & StoreStatus & ({
     path: string;
     handler: (r: RouteRequest) => Promise<void>;
 } | {
@@ -91,4 +111,5 @@ export type Route = {
     regex: RegExp;
     handler: (r: RouteRequest, match: RegExpMatchArray) => Promise<void>;
 });
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/server/validation.d.ts

@@ -1,11 +1,12 @@
 import type { IncomingMessage } from 'node:http';
-import type { Context, RememberOpts } from '../api.js';
-import { type JsonValue } from '../json.js';
-export declare function isJsonNumber(value: JsonValue | undefined): value is number;
-export declare function isJsonBoolean(value: JsonValue | undefined): value is boolean;
+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_SHORT_FIELD_LEN = 4096;
+export declare const MAX_LIST_LIMIT = 1000;
 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 first 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,27 +1,17 @@
-import { HttpError, isJsonObjectRecord, MAX_ID_LEN, readBody } from '../http-util.js';
-import { isJsonString } from '../json.js';
-export function isJsonNumber(value) {
-    return typeof value === 'number';
-}
-export function isJsonBoolean(value) {
-    return typeof value === 'boolean';
-}
-// 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.
+import { HttpError, MAX_ID_LEN, readBody } from '../util/http-util.js';
+import { isJsonString, isJsonObject } from '../util/json.js';
+// 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);
 }
+// Cap for short free-text HTTP fields (names, text, context, change summaries) on the object routes.
+export const MAX_SHORT_FIELD_LEN = 4096;
 // 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 function parseListLimit(limitRaw, defaultLimit = 100, maxLimit = 1000) {
+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);
@@ -30,7 +20,8 @@ export function parseListLimit(limitRaw, defaultLimit = 100, maxLimit = 1000) {
     }
     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 first under its own small cap. */
 export async function parseJsonBody(req, _authed) {
     return parseJsonObjectText(await readBody(req));
 }
@@ -39,7 +30,7 @@ export function parseJsonObjectText(raw) {
         return {};
     try {
         const parsed = JSON.parse(raw);
-        if (!isJsonObjectRecord(parsed)) {
+        if (!isJsonObject(parsed)) {
             throw new HttpError(400, 'request body must be a JSON object');
         }
         return parsed;
@@ -67,7 +58,7 @@ export function getCallerProject(body) {
     const v = body.project;
     if (v === undefined || v === null)
         return undefined;
-    if (!isJsonObjectRecord(v) || !isJsonString(v.name)) {
+    if (!isJsonObject(v) || !isJsonString(v.name)) {
         throw new HttpError(400, 'project must be an object with a "name" string');
     }
     if (v.aliases === undefined)
@@ -77,18 +68,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

@@ -1,81 +1,59 @@
-import { type Actor, authCreateSelf, type AuthCreateSelfOpts, type AuthCreateSelfResult, authRevoke, type AuthRevokeReply, type AuthRevokeResult, type Context } from './api.js';
-import { ForbiddenError, NotFoundError } from './api-errors.js';
-import type { ServeOpts, ServerHandle } from './server/types.js';
+import { type Actor, authCreateSelf, type AuthCreateSelfOpts, type AuthCreateSelfResult, authRevoke, type AuthRevokeReply, type AuthRevokeResult, type Context } from './api/index.js';
+import { ForbiddenError, NotFoundError } from './core/api-errors.js';
+export { serve } from './server/boot.js';
 export { authCreateSelf, authRevoke, ForbiddenError, NotFoundError, type AuthCreateSelfOpts, type AuthCreateSelfResult, type AuthRevokeReply, type AuthRevokeResult, type Context, type Actor, };
-export { isCrossSite, LOOPBACK_HOST_HEADER } from './http-util.js';
+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';
 export type { AddonCall, AddonRoute, AuthResolver, RateLimitSpec, ResolvedBearer, ServeOpts, ServerHandle } from './server/types.js';
-export { HttpError } from './http-util.js';
-export { promptHookContext, type CallerProject } from './prompt-hook.js';
-export type { JsonValue } from './json.js';
+export { HttpError } from './util/http-util.js';
+export { promptHookContext, type CallerProject } from './api/prompt-hook.js';
+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-port.js';
-export { entryAfterOutcome } from './memory.js';
-export { rejectionDigest, RejectedValueError } from './rejection.js';
-export { ownScopeTouches } from './recall-scope.js';
-export { BadRequestError, ConflictError } from './api-errors.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 { BadRequestError, ConflictError } from './core/api-errors.js';
 export type { HippoDbContext, StoreReply } from './api/types.js';
-export type { ApiKeyListItem, ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './auth.js';
-export type { KeysetPosition } from './keyset.js';
-export type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts } from './audit.js';
+export type { ApiKeyListItem, ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './store/auth.js';
+export type { KeysetPosition } from './util/keyset.js';
+export type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts } from './store/audit.js';
 export type { ContinuityBlock } from './api/recall-types.js';
-export type { ActiveGoals, GetActiveGoalsOpts, Goal, GoalRecallLogRow, RetrievalPolicy } from './goals.js';
-export type { MemoryEntry } from './memory.js';
-export type { ClassResolution, PlanningFallacyEvidence } from './predictions/planning-fallacy.js';
-export type { PredictionBaserate } from './predictions/store.js';
-export type { RecallTraceInput } from './recall-trace.js';
+export type { ActiveGoals, GetActiveGoalsOpts, Goal, GoalRecallLogRow, RetrievalPolicy } from './store/goals.js';
+export type { MemoryEntry } from './core/memory.js';
+export type { ClassResolution, PlanningFallacyEvidence } from './store/planning-fallacy-evidence.js';
+export type { PredictionBaserate } from './store/predictions.js';
+export type { RecallTraceInput } from './store/recall-trace.js';
 export type { StrengthenOptions } from './store/entry-writes.js';
 export type { OriginFilter, RecallScopeFilter, VectorCandidateSpec } from './store/search-rows.js';
 export type { ContinuityKey } from './store/sessions.js';
 export type { SessionEvent, TaskSnapshot } from './store/rows.js';
-export type { SessionHandoff } from './handoff.js';
+export type { SessionHandoff } from './core/handoff.js';
 export type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, RecentOrigins } from './store/candidates.js';
-export type { AmbientStoreFilter } from './ambient-store.js';
-export type { AmbientTallies } from './ambient.js';
-export type { TokenUse } from './token-ledger.js';
-export type { EmbeddingIndexState } from './embeddings.js';
-export type { PhysicsParticle } from './physics.js';
-export { StoreBusyError } from './db.js';
-export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows, type VectorMatch, type VectorRow } from './vector-store.js';
-export { bufferToFloat32, float32ToBuffer } from './physics-state.js';
-export { replacesIndex } from './embeddings.js';
-export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './recall-scope.js';
-export { SECRET_TAGS } from './secret-detect.js';
-export { tallyAmbientEntries } from './ambient.js';
-export { ftsTermParts, rarestFtsQuery } from './prompt-recall.js';
-export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db.js';
-export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api.js';
-export { isSharedStore } from './config.js';
-export { ownerOrSubject } from './api.js';
-export { bindSessionOwner } from './session-owners.js';
+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/vector-index.js';
+export type { PhysicsParticle } from './core/physics.js';
+export { StoreBusyError } from './db/index.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/vector-index.js';
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './store/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';
+export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db/index.js';
+export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api/index.js';
+export { isSharedStore } from './core/config.js';
+export { ownerOrSubject } from './api/index.js';
+export { bindSessionOwner } from './api/session-owners.js';
 export { preCompactForCaller, type CallerHookOutput, type CallerPreCompactRequest } from './capture/pre-compact-caller.js';
 export { compactResumeForCaller, type CallerCompactResumeRequest } from './capture/compact-resume-caller.js';
 export { saveCompactionItemsForCaller, type CallerItemsRequest, type CallerItemsResult } from './capture/compaction-items-caller.js';
 export { captureFailureForCaller, type CallerFailureRequest, type CallerFailureResult } from './capture/failure-caller.js';
 export { sessionEndHandoffForCaller, type CallerEvidence, type CallerSessionEndRequest, type CallerSessionEndResult } from './capture/session-end-caller.js';
 export type { WorkingState } from './capture/working-state.js';
-/**
- * Boot the HTTP daemon on host:port and write the pidfile under hippoRoot.
- *
- * Refuses non-loopback hosts at boot unless
- * HIPPO_REQUIRE_AUTH=1 is set. The auth middleware (buildContextWithAuth /
- * requireAuth) has shipped and every route checks it except GET /health
- * (public by design for platform health checks) and the two connector
- * webhooks in PUBLIC_ROUTES, which are HMAC-gated by their own signing
- * secrets and 404 when those secrets are unset, and any publicJson GET path. But the loopback
- * no-auth fallback inside buildContextWithAuth still admits unauthenticated
- * requests from a loopback remote address (unless they carry Forwarded,
- * X-Forwarded-For/-Host/-Proto, X-Real-IP, Cf-Connecting-Ip or True-Client-Ip, which mark a same-host proxy and get
- * a 401 like any keyless remote request), so binding to a non-loopback host
- * is only safe once that fallback is disabled with HIPPO_REQUIRE_AUTH=1,
- * which forces every request (loopback or not) through Bearer-token
- * validation. Without that env var set, a non-loopback bind would expose the
- * DB to the network with no auth, so we fail fast instead.
- *
- * Use port: 0 in tests to bind to an ephemeral port and read the actual
- * port back via server.address() after listen.
- */
-export declare function serve(opts: ServeOpts): Promise<ServerHandle>;
 //# sourceMappingURL=server.d.ts.map