hippo-memory 1.68.0 → 1.70.0

package/dist/server/key-check-bounds.js

@@ -0,0 +1,46 @@
+// Bounds on the scrypt work a bearer key check may start: how many derive at once, and how many one address starts for one key id.
+import { HttpError } from '../util/http-util.js';
+import { createRateLimiter } from './rate-limit.js';
+// libuv runs scrypt on a pool of four threads by default, so two stay free for file and DNS work.
+const MAX_IN_FLIGHT = 2;
+// Four rounds of two, so a burst of unproved keys waits its turn and no wait is longer than four derivations.
+const MAX_WAITING = 8;
+// Room for a mistyped or rotated secret; a secret is 160 random bits, so this bounds CPU, not guessing.
+const KEY_ADDRESS_BURST = 5;
+// One more try every 12 s: past its burst, an address starts at most five derivations a minute for one key id.
+const KEY_ADDRESS_TRIES_PER_SEC = 5 / 60;
+export function keyCheckBounds(maxKeys) {
+    // A bucket idle for a full refill is back at its burst, so dropping it then gives nothing away.
+    const idleEvictMs = (KEY_ADDRESS_BURST / KEY_ADDRESS_TRIES_PER_SEC) * 1000;
+    const perKeyAddress = createRateLimiter({ ratePerSec: KEY_ADDRESS_TRIES_PER_SEC, burst: KEY_ADDRESS_BURST, idleEvictMs, maxKeys });
+    let inFlight = 0;
+    const waiting = [];
+    return {
+        admit(keyId, address) {
+            // Each answers in the words an existing limit uses: the request limit's for a full queue, the address's scrypt bucket's for spent tries.
+            if (inFlight >= MAX_IN_FLIGHT && waiting.length >= MAX_WAITING)
+                throw new HttpError(429, 'rate limit exceeded', 1);
+            if (!perKeyAddress.check(`${keyId}\u0000${address}`)) {
+                throw new HttpError(429, 'too many key checks from this address', perKeyAddress.retryAfterSec);
+            }
+        },
+        async run(derive) {
+            if (inFlight < MAX_IN_FLIGHT)
+                inFlight++;
+            else
+                await new Promise((resolve) => { waiting.push(resolve); });
+            try {
+                return await derive();
+            }
+            finally {
+                // A waiter takes over this slot, so the count stays put across the handover and nothing slips in between.
+                const next = waiting.shift();
+                if (next)
+                    next();
+                else
+                    inFlight--;
+            }
+        },
+    };
+}
+//# sourceMappingURL=key-check-bounds.js.map

package/dist/server/lifecycle.js

@@ -1,4 +1,4 @@
-import { log } from '../log.js';
+import { log } from '../util/log.js';
 /**
  * Stop accepting, end streams at once (they never finish on their own), give other in-flight
  * requests up to `drainMs`, then close whatever is left.

package/dist/server/mcp-http.d.ts

@@ -1,11 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { Context } from '../api.js';
-import { type McpContext } from '../mcp/server.js';
-import type { CallerProject } from '../prompt-hook.js';
+import type { CallerProject } from '../api/prompt-hook.js';
 import type { ResolvedServeOpts } from './types.js';
 /** On a shared store, the caller's project from X-Hippo-Project and the comma-separated X-Hippo-Project-Aliases; any other store ignores both. */
 export declare function callerProjectFromHeaders(req: IncomingMessage, hippoRoot: string): CallerProject | undefined;
-export declare function mcpContextFor(ctx: Context, clientKey: string, autoSleep: McpContext['autoSleep'], project?: CallerProject): McpContext;
 export declare function handleMcpPost(req: IncomingMessage, res: ServerResponse, opts: ResolvedServeOpts): Promise<void>;
 export declare function handleMcpStream(req: IncomingMessage, res: ServerResponse, opts: ResolvedServeOpts, streamSlots: Map<string, number>): Promise<void>;
 //# sourceMappingURL=mcp-http.d.ts.map

package/dist/server/mcp-http.js

@@ -1,14 +1,17 @@
 // MCP over HTTP: POST /mcp and the GET /mcp/stream SSE keepalive.
-import { envMcpSseHeartbeatMs, envMcpSseMaxAgeSec, envMcpSseMaxStreams } from '../env.js';
+import { envMcpSseHeartbeatMs, envMcpSseMaxAgeSec, envMcpSseMaxStreams } from '../util/env.js';
 import { createHash } from 'node:crypto';
-import { isSharedStore } from '../config.js';
+import { isSharedStore } from '../core/config.js';
 import { handleMcpRequest, mcpErrorResponse } from '../mcp/server.js';
-import { HttpError, isJsonObjectRecord, readBody, sendJson } from '../http-util.js';
-import { assertCallerProject } from '../project-identity.js';
+import { HttpError, readBody, sendJson } from '../util/http-util.js';
+import { assertCallerProject } from '../core/project-identity.js';
 import { buildContextWithAuth, heartbeatVerdict, readAuthHeader, requireAuth } from './auth.js';
-import { clientIpForRateLimit } from './client-ip.js';
-import { requestIds } from './request.js';
-import { isJsonString } from '../json.js';
+import { clientLimitKey, subscriberKey } from './client-ip.js';
+import { noteAccess } from './request.js';
+import { isJsonString, isJsonObject } from '../util/json.js';
+import { FINGERPRINT_HEX_CHARS } from '../util/token-text.js';
+const DEFAULT_SSE_HEARTBEAT_MS = 60000;
+const DEFAULT_SSE_MAX_AGE_SEC = 3600;
 /**
  * Build a per-client key for MCP state isolation under HTTP-MCP. Used by
  * mcp/server.ts to scope `lastRecalledIds` to the calling client so two
@@ -23,9 +26,9 @@ import { isJsonString } from '../json.js';
 function buildMcpClientKey(req) {
     const auth = readAuthHeader(req);
     const tokenHash = auth.kind === 'bearer'
-        ? createHash('sha256').update(auth.token).digest('hex').slice(0, 16)
+        ? createHash('sha256').update(auth.token).digest('hex').slice(0, FINGERPRINT_HEX_CHARS)
         : 'noauth';
-    const addr = req.socket.remoteAddress ?? 'unknown';
+    const addr = subscriberKey(req.socket.remoteAddress ?? 'unknown');
     return `http:${tokenHash}:${addr}`;
 }
 // ── MCP-over-HTTP/SSE transport ──
@@ -77,7 +80,7 @@ export function callerProjectFromHeaders(req, hippoRoot) {
     assertCallerProject({ name, aliases });
     return { name, legacyName: name, aliases };
 }
-export function mcpContextFor(ctx, clientKey, autoSleep, project) {
+function mcpContextFor(ctx, clientKey, autoSleep, project) {
     const mcpCtx = {
         hippoRoot: ctx.hippoRoot,
         tenantId: ctx.tenantId,
@@ -104,6 +107,7 @@ export async function handleMcpPost(req, res, opts) {
     // pull tenant from HIPPO_TENANT, dropping a valid Bearer for tenant B
     // back to whatever the env says.
     const ctx = await buildContextWithAuth(req, opts);
+    noteAccess(req, { tenant: ctx.tenantId });
     const project = callerProjectFromHeaders(req, ctx.hippoRoot);
     const raw = await readBody(req);
     let mcpReq;
@@ -113,7 +117,7 @@ export async function handleMcpPost(req, res, opts) {
     catch {
         throw new HttpError(400, 'invalid JSON-RPC body');
     }
-    if (!isJsonObjectRecord(mcpReq) || !isJsonString(mcpReq.method)) {
+    if (!isJsonObject(mcpReq) || !isJsonString(mcpReq.method)) {
         throw new HttpError(400, 'JSON-RPC body must include a method string');
     }
     // SAFETY: validated above as a plain JSON object carrying a string method;
@@ -125,7 +129,7 @@ export async function handleMcpPost(req, res, opts) {
         mcpRes = await handleMcpRequest(rpcReq, mcpContextFor(ctx, buildMcpClientKey(req), opts.autoSleep, project));
     }
     catch (err) {
-        mcpRes = mcpErrorResponse(rpcReq.id, err, requestIds.get(req));
+        mcpRes = mcpErrorResponse(rpcReq.id, err);
     }
     if (mcpRes === null) {
         // Notification — no body, 202 Accepted.
@@ -141,8 +145,8 @@ const DEFAULT_MAX_STREAMS_PER_CLIENT = 8;
 function streamSlotKey(req) {
     const auth = readAuthHeader(req);
     if (auth.kind === 'bearer')
-        return `key:${createHash('sha256').update(auth.token).digest('hex').slice(0, 16)}`;
-    return `ip:${clientIpForRateLimit(req)}`;
+        return `key:${createHash('sha256').update(auth.token).digest('hex').slice(0, FINGERPRINT_HEX_CHARS)}`;
+    return `ip:${clientLimitKey(req)}`;
 }
 /** Takes a stream slot or throws 429; the slot is released once, when the response closes. */
 function acquireStreamSlot(req, res, slots) {
@@ -181,8 +185,11 @@ export async function handleMcpStream(req, res, opts, streamSlots) {
     //     with reason='max_age_exceeded' when reached.
     //   - MCP_SSE_HEARTBEAT_MS (default 60000) lets tests run with a short
     //     interval without waiting a full minute.
-    const heartbeatMs = envMcpSseHeartbeatMs() ?? 60000;
-    const maxAgeMs = (envMcpSseMaxAgeSec() ?? 3600) * 1000;
+    keepStreamAlive(req, res, opts);
+}
+function keepStreamAlive(req, res, opts) {
+    const heartbeatMs = envMcpSseHeartbeatMs() ?? DEFAULT_SSE_HEARTBEAT_MS;
+    const maxAgeMs = (envMcpSseMaxAgeSec() ?? DEFAULT_SSE_MAX_AGE_SEC) * 1000;
     const startedAt = Date.now();
     let closed = false;
     let checking = false;
@@ -190,14 +197,7 @@ export async function handleMcpStream(req, res, opts, streamSlots) {
         if (closed)
             return;
         closed = true;
-        try {
-            res.write(`event: closed\ndata: ${JSON.stringify({ reason })}\n\n`);
-        }
-        catch { /* socket already gone */ }
-        try {
-            res.end();
-        }
-        catch { /* socket already gone */ }
+        endStreamWithReason(res, reason);
     };
     const ping = setInterval(() => {
         if (closed) {
@@ -239,4 +239,14 @@ export async function handleMcpStream(req, res, opts, streamSlots) {
         clearInterval(ping);
     });
 }
+function endStreamWithReason(res, reason) {
+    try {
+        res.write(`event: closed\ndata: ${JSON.stringify({ reason })}\n\n`);
+    }
+    catch { /* socket already gone */ }
+    try {
+        res.end();
+    }
+    catch { /* socket already gone */ }
+}
 //# sourceMappingURL=mcp-http.js.map

package/dist/server/ready.d.ts

@@ -0,0 +1,7 @@
+import type { HippoStore } from '../store/index.js';
+export type ReadyProbe = () => Promise<boolean>;
+/** The shared probe for a served store, so every request to that server draws on one remembered answer. */
+export declare function readyProbeFor(store: HippoStore, readiness: {
+    ping(): Promise<void>;
+}, now?: () => number): ReadyProbe;
+//# sourceMappingURL=ready.d.ts.map

package/dist/server/ready.js

@@ -0,0 +1,38 @@
+import { SERVER_DB_WAIT_MS, runWithRequestStores } from '../db/index.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+// A prober must never see a 429, so the store read is bounded by remembering its answer instead of rate-limiting the route.
+const READY_WINDOW_MS = 1000;
+/** True when the store answered; one read per window whatever the caller count, and a failed read is remembered for the same window. */
+function createReadyProbe(readiness, now = Date.now) {
+    let answer;
+    let inFlight;
+    async function read() {
+        let ok = true;
+        try {
+            await runWithRequestStores(() => readiness.ping(), { busyWaitMs: SERVER_DB_WAIT_MS });
+        }
+        catch (err) {
+            log.warn(`GET /ready: the store did not answer: ${errorMessage(err)}`, errorFields(err));
+            ok = false;
+        }
+        answer = { at: now(), ok };
+        return ok;
+    }
+    return () => {
+        if (answer !== undefined && now() - answer.at < READY_WINDOW_MS)
+            return Promise.resolve(answer.ok);
+        inFlight ??= read().finally(() => { inFlight = undefined; });
+        return inFlight;
+    };
+}
+const probes = new WeakMap();
+/** The shared probe for a served store, so every request to that server draws on one remembered answer. */
+export function readyProbeFor(store, readiness, now = Date.now) {
+    let probe = probes.get(store);
+    if (probe === undefined) {
+        probe = createReadyProbe(readiness, now);
+        probes.set(store, probe);
+    }
+    return probe;
+}
+//# sourceMappingURL=ready.js.map

package/dist/server/request.d.ts

@@ -1,13 +1,20 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-/** The caller's `X-Request-Id` when it is a short plain token, else a fresh UUID. */
-export declare function resolveRequestId(header: string | string[] | undefined): string;
 /** One line per failed request; 4xx is the caller's mistake, a busy 503 is back-pressure and a 501 is a route not on this store, so none logs as an error. */
-export declare function logRequestFailure<E>(req: IncomingMessage, err: E, requestId: string, status: number): void;
+export declare function logRequestFailure<E>(req: IncomingMessage, err: E, status: number): void;
 /** The status and client message for a failed request; a held write lock is a retryable 503, never a 500. */
 export declare function replyFor<E>(err: E): {
     status: number;
     message: string;
 };
+/** What the route layer learned about a request, for its access line. */
+interface AccessNote {
+    route?: string;
+    tenant?: string;
+}
+/** Names the matched route (the table's pattern, never the path sent) or the caller's tenant for the request's access line. */
+export declare function noteAccess(req: IncomingMessage, note: AccessNote): void;
+/** The request's id, after stamping the headers every reply carries and starting the slow-request watchdog and the access line. */
+export declare function openRequest(req: IncomingMessage, res: ServerResponse, slowWarnMs?: number): string;
 export declare function sendError(res: ServerResponse, status: number, message: string): void;
 interface ParsedRoute {
     method: string;
@@ -16,7 +23,6 @@ interface ParsedRoute {
 }
 export declare function parseRequest(req: IncomingMessage): ParsedRoute;
 export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
-export declare const requestIds: WeakMap<IncomingMessage, string>;
 /**
  * Reject URL-encoded slashes in path segments BEFORE the URL parser decodes
  * them — otherwise `%2F` becomes `/`, path-split runs, and the route either

package/dist/server/request.js

@@ -1,29 +1,82 @@
 import { randomUUID } from 'node:crypto';
-import { isStoreBusy, STORE_BUSY_MESSAGE } from '../db.js';
-import { errorFields, log } from '../log.js';
-import { HttpError, mapApiError, sendJson } from '../http-util.js';
+import { isStoreBusy, STORE_BUSY_MESSAGE } from '../db/index.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { HttpError, mapApiError, sendJson } from '../util/http-util.js';
 // The caller's id lands in a response header and in logs, so only a short plain token is echoed back.
 const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
 /** The caller's `X-Request-Id` when it is a short plain token, else a fresh UUID. */
-export function resolveRequestId(header) {
+function resolveRequestId(header) {
     const value = Array.isArray(header) ? undefined : header;
     return value && REQUEST_ID_RE.test(value) ? value : randomUUID();
 }
 /** One line per failed request; 4xx is the caller's mistake, a busy 503 is back-pressure and a 501 is a route not on this store, so none logs as an error. */
-export function logRequestFailure(req, err, requestId, status) {
-    const message = err instanceof Error ? err.message : String(err);
+export function logRequestFailure(req, err, status) {
+    const message = errorMessage(err);
     const line = `${req.method ?? 'GET'} ${(req.url ?? '/').split('?')[0]} failed: ${message}`;
-    if (isStoreBusy(err))
-        log.warn(line, { requestId, status });
+    // A 5xx that tells the caller when to retry is back-pressure too.
+    if (isStoreBusy(err) || (status >= 500 && err instanceof HttpError && err.retryAfterSec !== undefined))
+        log.warn(line, { status });
     else if (status >= 500 && status !== 501)
-        log.error(line, { requestId, status, ...errorFields(err) });
+        log.error(line, { status, ...errorFields(err) });
     else
-        log.info(line, { requestId, status });
+        log.info(line, { status });
 }
 /** The status and client message for a failed request; a held write lock is a retryable 503, never a 500. */
 export function replyFor(err) {
     return isStoreBusy(err) ? { status: 503, message: STORE_BUSY_MESSAGE } : mapApiError(err);
 }
+// Above the 30 s body deadline and the 5 s resolver deadline, so a request those govern is answered before it is called slow.
+const SLOW_REQUEST_WARN_MS = 60_000;
+/** Logs one warn when `res` has sent nothing after `afterMs`. It never ends the request or touches the reply; the timer goes when the reply finishes or the socket closes. */
+function watchSlowRequest(req, res, requestId, afterMs = SLOW_REQUEST_WARN_MS) {
+    const startedAt = Date.now();
+    const timer = setTimeout(() => {
+        // A reply already under way is a stream doing its job, not a stuck request.
+        if (res.headersSent)
+            return;
+        log.warn(`${req.method ?? 'GET'} ${(req.url ?? '/').split('?')[0]} is still running`, { requestId, elapsedMs: Date.now() - startedAt });
+    }, afterMs);
+    // The watchdog alone must never keep the process alive.
+    timer.unref();
+    const clear = () => clearTimeout(timer);
+    res.once('finish', clear);
+    res.once('close', clear);
+}
+const accessNotes = new WeakMap();
+// A path that matched no route is caller data, so the access line never repeats it.
+const UNMATCHED_ROUTE = 'unmatched';
+/** Names the matched route (the table's pattern, never the path sent) or the caller's tenant for the request's access line. */
+export function noteAccess(req, note) {
+    const held = accessNotes.get(req);
+    if (held)
+        Object.assign(held, note);
+}
+/** One info line per finished request. A path id and a query string can both hold caller data, so the line carries neither. */
+function logAccessWhenFinished(req, res, requestId) {
+    const note = {};
+    accessNotes.set(req, note);
+    const startedAt = performance.now();
+    res.once('finish', () => {
+        log.info('request', {
+            requestId,
+            method: req.method ?? 'GET',
+            route: note.route ?? UNMATCHED_ROUTE,
+            status: res.statusCode,
+            durationMs: Math.round(performance.now() - startedAt),
+            tenant: note.tenant,
+        });
+    });
+}
+/** The request's id, after stamping the headers every reply carries and starting the slow-request watchdog and the access line. */
+export function openRequest(req, res, slowWarnMs) {
+    const requestId = resolveRequestId(req.headers['x-request-id']);
+    res.setHeader('X-Request-Id', requestId);
+    // Memory text is caller-written, so no browser may guess a reply into HTML or script.
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    watchSlowRequest(req, res, requestId, slowWarnMs);
+    logAccessWhenFinished(req, res, requestId);
+    return requestId;
+}
 export function sendError(res, status, message) {
     sendJson(res, status, { error: message });
 }
@@ -82,8 +135,6 @@ export function matchPath(pattern, path) {
     }
     return params;
 }
-// The auth helpers only see the request, so its id rides here for their log lines.
-export const requestIds = new WeakMap();
 /**
  * Reject URL-encoded slashes in path segments BEFORE the URL parser decodes
  * them — otherwise `%2F` becomes `/`, path-split runs, and the route either

package/dist/server/route-table.d.ts

@@ -0,0 +1,15 @@
+import type { AddonRoute, ResolvedServeOpts, RouteRequest } from './types.js';
+import type { JsonValue } from '../util/json.js';
+export declare function isPublicRoute(method: string, path: string): boolean;
+/** Run the first /v1 route whose method and path match. */
+export declare function dispatchV1Route(r: RouteRequest, method: string, path: string): Promise<boolean>;
+/** Boot-time check: an add-on path must be plain, unique and not one core serves, so no add-on shadows a core route or hides from dispatch. */
+export declare function assertAddonRoutes(routes: readonly AddonRoute[]): void;
+/** Boot-time check and serialization: a public path that a core GET route serves would open that route to anyone. */
+export declare function assertPublicJson(publicJson: Readonly<Record<string, JsonValue>>): ReadonlyMap<string, string>;
+/** Core authenticates and parses before the handler runs, so an add-on route gets the same 401, 400 and 501 as a core one. */
+export declare function dispatchAddonRoute({ req, res, opts }: RouteRequest, method: string, path: string): Promise<boolean>;
+/** No auth, body read or store access, so a caller with no key gets it under any store. */
+export declare function dispatchPublicJson({ req, res, opts }: RouteRequest, method: string, path: string): boolean;
+export declare function assertSqliteStore(opts: ResolvedServeOpts): void;
+//# sourceMappingURL=route-table.d.ts.map

package/dist/server/route-table.js

@@ -0,0 +1,209 @@
+import { withSqliteOffLoop } from '../db/index.js';
+import { hasGroup } from '../store/index.js';
+import { runsOffLoop } from '../store/sqlite/worker-store.js';
+import { HttpError, JSON_HEADERS, sendJson, STORE_NOT_PORTED_MESSAGE } from '../util/http-util.js';
+import { buildContextWithAuth, requireAuth } from './auth.js';
+import { matchPath, noteAccess } from './request.js';
+import { handleApproveQuarantine, handleCreateAuthKey, handleListAudit, handleListAuthKeys, handleListQuarantine, handleRejectQuarantine, handleRevokeAuthKey } from './routes/admin.js';
+import { handleCloseCustomerNote, handleCreateCustomerNote, handleGetCustomerNote, handleListCustomerNotes, handleSupersedeCustomerNote } from './routes/customer-notes.js';
+import { handleCloseDecision, handleCreateDecision, handleGetDecision, handleListDecisions, handleSupersedeDecision } from './routes/decisions.js';
+import { handleCloseIncident, handleCreateIncident, handleGetIncident, handleListIncidents, handleResolveIncident } from './routes/incidents.js';
+import { handleApplyOutcome, handleArchiveMemory, handleCreateMemory, handleForgetMemory, handleGetGraph, handlePromoteMemory, handleSleep, handleSupersedeMemory } from './routes/memories.js';
+import { handleClosePolicy, handleCreatePolicy, handleGetPolicy, handleListPolicies, handlePoliciesAsOf, handleSupersedePolicy } from './routes/policies.js';
+import { handleClosePrediction, handleCreatePrediction, handleGetPrediction, handleListPredictions, handlePredictionStats } from './routes/predictions.js';
+import { handleCloseProcess, handleCreateProcess, handleGetProcess, handleListProcesses, handleSupersedeProcess } from './routes/processes.js';
+import { handleCloseProjectBrief, handleCreateProjectBrief, handleGetProjectBrief, handleListProjectBriefs, handleRefreshProjectBrief, handleSupersedeProjectBrief } from './routes/project-briefs.js';
+import { handleAssembleSession, handleDrillRecall, handleGetContext, handleRecallMemories } from './routes/recall.js';
+import { handleCloseSkill, handleCreateSkill, handleExportSkills, handleGetSkill, handleListSkills, handleSupersedeSkill } from './routes/skills.js';
+import { parseJsonBody } from './validation.js';
+// Review patch #2: explicit allow-list for unauthenticated /v1/* routes.
+// New unauth routes MUST be added here AND get a corresponding entry in
+// tests/server-bearer-lockdown.test.ts. Do not gate auth elsewhere by
+// `path.startsWith` — pattern-positional auth is bypass-by-accident.
+//
+// The route handlers consult `isPublicRoute` before invoking
+// `buildContextWithAuth` / `requireAuth`. Adding a route here without
+// adding the corresponding `isPublicRoute` short-circuit in a handler is
+// a no-op (auth still applies), so the failure mode is fail-closed.
+// The only other unauthenticated paths are ServeOpts.publicJson's: GET only, checked at boot by assertPublicJson.
+const PUBLIC_ROUTES = new Set([
+    'POST /v1/connectors/slack/events',
+    'POST /v1/connectors/github/events',
+]);
+export function isPublicRoute(method, path) {
+    return PUBLIC_ROUTES.has(`${method} ${path}`);
+}
+/** The /v1 routes in dispatch order; the first entry whose method and path match handles the request. */
+const V1_ROUTES = [
+    { method: 'POST', path: '/v1/memories', storeReady: 'entryWrites', loop: 'off', handler: handleCreateMemory },
+    { method: 'GET', path: '/v1/graph', storeReady: 'graphReads', loop: 'off', handler: handleGetGraph },
+    { method: 'GET', path: '/v1/memories', storeReady: 'base', loop: 'off', handler: handleRecallMemories },
+    { method: 'GET', pattern: '/v1/sessions/:id/assemble', storeReady: 'dagReads', loop: 'off', handler: handleAssembleSession },
+    { method: 'GET', pattern: '/v1/recall/drill/:id', storeReady: 'dagReads', handler: handleDrillRecall },
+    { method: 'POST', pattern: '/v1/memories/:id/archive', storeReady: 'entryWrites', loop: 'off', handler: handleArchiveMemory },
+    { method: 'POST', pattern: '/v1/memories/:id/supersede', storeReady: 'entryWrites', loop: 'off', handler: handleSupersedeMemory },
+    { method: 'POST', pattern: '/v1/memories/:id/promote', sqliteOnly: 'copies a memory between the two local hippo.db files', handler: handlePromoteMemory },
+    { method: 'DELETE', pattern: '/v1/memories/:id', storeReady: 'entryWrites', loop: 'off', handler: handleForgetMemory },
+    { method: 'POST', path: '/v1/outcome', storeReady: 'entryWrites', handler: handleApplyOutcome },
+    { method: 'GET', path: '/v1/context', storeReady: 'contextReads', handler: handleGetContext },
+    { method: 'POST', path: '/v1/sleep', sqliteOnly: 'consolidates every tenant under the local hippo root in this process', handler: handleSleep },
+    { method: 'POST', path: '/v1/auth/keys', storeReady: 'keyWrites', loop: 'off', handler: handleCreateAuthKey },
+    { method: 'GET', path: '/v1/auth/keys', storeReady: 'keyWrites', loop: 'off', handler: handleListAuthKeys },
+    { method: 'DELETE', pattern: '/v1/auth/keys/:keyId', storeReady: 'keyAudit', loop: 'off', handler: handleRevokeAuthKey },
+    { method: 'GET', path: '/v1/quarantine', storeReady: 'quarantine', loop: 'off', handler: handleListQuarantine },
+    { method: 'POST', pattern: '/v1/quarantine/:id/approve', storeReady: 'quarantine', loop: 'off', handler: handleApproveQuarantine },
+    { method: 'POST', pattern: '/v1/quarantine/:id/reject', storeReady: 'quarantine', loop: 'off', handler: handleRejectQuarantine },
+    { method: 'GET', path: '/v1/audit', storeReady: 'auditLog', loop: 'off', handler: handleListAudit },
+    { method: 'POST', path: '/v1/predictions', storeReady: 'predictions', loop: 'off', handler: handleCreatePrediction },
+    { method: 'GET', path: '/v1/predictions', storeReady: 'predictions', loop: 'off', handler: handleListPredictions },
+    { method: 'GET', path: '/v1/predictions/stats', storeReady: 'predictions', loop: 'off', handler: handlePredictionStats },
+    { method: 'GET', regex: /^\/v1\/predictions\/(\d+)$/, storeReady: 'predictions', loop: 'off', handler: handleGetPrediction },
+    { method: 'POST', regex: /^\/v1\/predictions\/(\d+)\/close$/, storeReady: 'predictions', loop: 'off', handler: handleClosePrediction },
+    { method: 'POST', path: '/v1/decisions', storeReady: 'objects', handler: handleCreateDecision },
+    { method: 'GET', path: '/v1/decisions', storeReady: 'objects', handler: handleListDecisions },
+    { method: 'POST', regex: /^\/v1\/decisions\/(\d+)\/supersede$/, storeReady: 'objects', handler: handleSupersedeDecision },
+    { method: 'POST', regex: /^\/v1\/decisions\/(\d+)\/close$/, storeReady: 'objects', handler: handleCloseDecision },
+    { method: 'GET', regex: /^\/v1\/decisions\/(\d+)$/, storeReady: 'objects', handler: handleGetDecision },
+    { method: 'POST', path: '/v1/incidents', storeReady: 'objects', handler: handleCreateIncident },
+    { method: 'GET', path: '/v1/incidents', storeReady: 'objects', handler: handleListIncidents },
+    { method: 'POST', regex: /^\/v1\/incidents\/(\d+)\/resolve$/, storeReady: 'objects', handler: handleResolveIncident },
+    { method: 'POST', regex: /^\/v1\/incidents\/(\d+)\/close$/, storeReady: 'objects', handler: handleCloseIncident },
+    { method: 'GET', regex: /^\/v1\/incidents\/(\d+)$/, storeReady: 'objects', handler: handleGetIncident },
+    { method: 'POST', path: '/v1/processes', storeReady: 'objects', handler: handleCreateProcess },
+    { method: 'GET', path: '/v1/processes', storeReady: 'objects', handler: handleListProcesses },
+    { method: 'POST', regex: /^\/v1\/processes\/(\d+)\/supersede$/, storeReady: 'objects', handler: handleSupersedeProcess },
+    { method: 'POST', regex: /^\/v1\/processes\/(\d+)\/close$/, storeReady: 'objects', handler: handleCloseProcess },
+    { method: 'GET', regex: /^\/v1\/processes\/(\d+)$/, storeReady: 'objects', handler: handleGetProcess },
+    { method: 'POST', path: '/v1/policies', storeReady: 'objects', handler: handleCreatePolicy },
+    { method: 'GET', path: '/v1/policies', storeReady: 'objects', handler: handleListPolicies },
+    { method: 'GET', path: '/v1/policies/asof', storeReady: 'objects', handler: handlePoliciesAsOf },
+    { method: 'POST', regex: /^\/v1\/policies\/(\d+)\/supersede$/, storeReady: 'objects', handler: handleSupersedePolicy },
+    { method: 'POST', regex: /^\/v1\/policies\/(\d+)\/close$/, storeReady: 'objects', handler: handleClosePolicy },
+    { method: 'GET', regex: /^\/v1\/policies\/(\d+)$/, storeReady: 'objects', handler: handleGetPolicy },
+    { method: 'POST', path: '/v1/skills', storeReady: 'objects', handler: handleCreateSkill },
+    { method: 'GET', path: '/v1/skills', storeReady: 'objects', handler: handleListSkills },
+    { method: 'GET', path: '/v1/skills/export', storeReady: 'objects', handler: handleExportSkills },
+    { method: 'POST', regex: /^\/v1\/skills\/(\d+)\/supersede$/, storeReady: 'objects', handler: handleSupersedeSkill },
+    { method: 'POST', regex: /^\/v1\/skills\/(\d+)\/close$/, storeReady: 'objects', handler: handleCloseSkill },
+    { method: 'GET', regex: /^\/v1\/skills\/(\d+)$/, storeReady: 'objects', handler: handleGetSkill },
+    { method: 'POST', path: '/v1/project-briefs', storeReady: 'objects', handler: handleCreateProjectBrief },
+    { method: 'GET', path: '/v1/project-briefs', storeReady: 'objects', handler: handleListProjectBriefs },
+    { method: 'POST', path: '/v1/project-briefs/refresh', storeReady: 'objects', handler: handleRefreshProjectBrief },
+    { method: 'POST', regex: /^\/v1\/project-briefs\/(\d+)\/supersede$/, storeReady: 'objects', handler: handleSupersedeProjectBrief },
+    { method: 'POST', regex: /^\/v1\/project-briefs\/(\d+)\/close$/, storeReady: 'objects', handler: handleCloseProjectBrief },
+    { method: 'GET', regex: /^\/v1\/project-briefs\/(\d+)$/, storeReady: 'objects', handler: handleGetProjectBrief },
+    { method: 'POST', path: '/v1/customer-notes', storeReady: 'objects', handler: handleCreateCustomerNote },
+    { method: 'GET', path: '/v1/customer-notes', storeReady: 'objects', handler: handleListCustomerNotes },
+    { method: 'POST', regex: /^\/v1\/customer-notes\/(\d+)\/supersede$/, storeReady: 'objects', handler: handleSupersedeCustomerNote },
+    { method: 'POST', regex: /^\/v1\/customer-notes\/(\d+)\/close$/, storeReady: 'objects', handler: handleCloseCustomerNote },
+    { method: 'GET', regex: /^\/v1\/customer-notes\/(\d+)$/, storeReady: 'objects', handler: handleGetCustomerNote },
+];
+/** The route's handler bound to this request's path params, or null when method or path differ. The matcher runs before the
+ *  method check, as the inline route blocks did, so a malformed `%` escape still throws from matchPath on any method. */
+function routeMatches(route, method, path) {
+    if ('path' in route)
+        return method === route.method && path === route.path ? route.handler : null;
+    if ('pattern' in route) {
+        const params = matchPath(route.pattern, path);
+        return method === route.method && params ? (r) => route.handler(r, params) : null;
+    }
+    const match = path.match(route.regex);
+    return method === route.method && match ? (r) => route.handler(r, match) : null;
+}
+/** The route as the access line names it; a regex route reads as its pattern would, so no line carries a caller's id. */
+function routeLabel(route) {
+    if ('path' in route)
+        return route.path;
+    if ('pattern' in route)
+        return route.pattern;
+    return route.regex.source.replace(/^\^|\$$/g, '').replaceAll('\\/', '/').replaceAll('(\\d+)', ':id');
+}
+/** Run the first /v1 route whose method and path match. */
+export async function dispatchV1Route(r, method, path) {
+    for (const route of V1_ROUTES) {
+        const run = routeMatches(route, method, path);
+        if (run === null)
+            continue;
+        noteAccess(r.req, { route: routeLabel(route) });
+        await refuseUnportedRoute(r.req, r.opts, route.storeReady);
+        // Only a store with worker threads has moved the route's SQLite work; under any other the handler still opens hippo.db itself.
+        await (route.loop === 'off' && runsOffLoop(r.opts.store) ? withSqliteOffLoop(() => run(r)) : run(r));
+        return true;
+    }
+    return false;
+}
+const PLAIN_SEGMENT_RE = /^[A-Za-z0-9._~-]+$/;
+function isPlainV1Path(path) {
+    return path.startsWith('/v1/') && new URL(path, 'http://h').pathname === path
+        && path.slice('/v1/'.length).split('/').every((segment) => PLAIN_SEGMENT_RE.test(segment));
+}
+// A plain path never holds a `%`, so matchPath cannot throw here.
+function isCorePath(method, path) {
+    return PUBLIC_ROUTES.has(`${method} ${path}`) || V1_ROUTES.some((route) => routeMatches(route, method, path) !== null);
+}
+/** Boot-time check: an add-on path must be plain, unique and not one core serves, so no add-on shadows a core route or hides from dispatch. */
+export function assertAddonRoutes(routes) {
+    const seen = new Set();
+    for (const { path } of routes) {
+        if (!isPlainV1Path(path))
+            throw new Error(`add-on route '${path}' is not a plain /v1/ path (segments use A-Z a-z 0-9 . _ ~ -)`);
+        if (seen.has(path))
+            throw new Error(`add-on route '${path}' is registered twice`);
+        if (isCorePath('POST', path))
+            throw new Error(`add-on route '${path}' is already served by core`);
+        seen.add(path);
+    }
+}
+const PUBLIC_JSON_MAX_BYTES = 64 * 1024;
+/** Boot-time check and serialization: a public path that a core GET route serves would open that route to anyone. */
+export function assertPublicJson(publicJson) {
+    const bodies = new Map();
+    for (const [path, value] of Object.entries(publicJson)) {
+        if (!isPlainV1Path(path))
+            throw new Error(`public JSON path '${path}' is not a plain /v1/ path (segments use A-Z a-z 0-9 . _ ~ -)`);
+        if (isCorePath('GET', path))
+            throw new Error(`public JSON path '${path}' is already served by core`);
+        const text = JSON.stringify(value);
+        if (text === undefined)
+            throw new Error(`public JSON at '${path}' is not JSON`);
+        if (Buffer.byteLength(text) > PUBLIC_JSON_MAX_BYTES)
+            throw new Error(`public JSON at '${path}' is over 64 KiB`);
+        bodies.set(path, text);
+    }
+    return bodies;
+}
+/** Core authenticates and parses before the handler runs, so an add-on route gets the same 401, 400 and 501 as a core one. */
+export async function dispatchAddonRoute({ req, res, opts }, method, path) {
+    const route = method === 'POST' ? opts.routes?.find((r) => r.path === path) : undefined;
+    if (!route)
+        return false;
+    noteAccess(req, { route: route.path });
+    await refuseUnportedRoute(req, opts, route.storeReady);
+    const ctx = await buildContextWithAuth(req, opts);
+    noteAccess(req, { tenant: ctx.tenantId });
+    const body = await parseJsonBody(req, ctx);
+    sendJson(res, 200, await route.handler({ ctx, body }));
+    return true;
+}
+/** No auth, body read or store access, so a caller with no key gets it under any store. */
+export function dispatchPublicJson({ req, res, opts }, method, path) {
+    const text = method === 'GET' ? opts.publicJsonBodies.get(path) : undefined;
+    if (text === undefined)
+        return false;
+    noteAccess(req, { route: path });
+    res.writeHead(200, { ...JSON_HEADERS, 'cache-control': 'no-store' });
+    res.end(text);
+    return true;
+}
+export function assertSqliteStore(opts) {
+    if (opts.store.kind !== 'sqlite')
+        throw new HttpError(501, STORE_NOT_PORTED_MESSAGE);
+}
+/** Under another store, a route that names no group, or one the store lacks, answers 501 without running; the caller is checked first, so a bad key is still a 401. */
+async function refuseUnportedRoute(req, opts, group) {
+    if (opts.store.kind === 'sqlite' || (group !== undefined && hasGroup(opts.store, group)))
+        return;
+    await requireAuth(req, opts);
+    assertSqliteStore(opts);
+}
+//# sourceMappingURL=route-table.js.map