hippo-memory 1.71.0 → 1.72.0

package/dist/search/vector.js

@@ -1,10 +1,11 @@
-import { cosineOf, indexNeedsRebuild } from '../store/embeddings/index.js';
+import { cosineOf } from '../core/cosine.js';
+import { indexNeedsRebuild } from '../store/embeddings/index.js';
 import { indexedModel } from '../store/vector-index.js';
-import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
-import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { resolveEmbeddingProvider } from '../embeddings/provider.js';
+import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
 import { errorMessage, log } from '../util/log.js';
 import { envQueryEmbedTimeoutMs } from '../util/env.js';
-import { requireGroup, sqliteStore } from '../store/index.js';
+import { requireGroup } from '../store/index.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { currentEntries } from './as-of.js';
 // Jev's default budget (rerankers/jev.ts): each is one off-box call that a recall waits on.
@@ -17,11 +18,8 @@ function queryEmbedBudgetMs() {
 export function startQueryEmbedDeadline() {
     return AbortSignal.timeout(queryEmbedBudgetMs());
 }
-/** The query's vector, or null when an API provider outlasts `deadline`; any other provider failure throws as before. */
+/** The query's vector, or null when the provider outlasts `deadline`: an API call, or a local model still downloading. Any other failure throws. */
 export async function embedQueryBy(deadline, provider, query) {
-    // No signal stops an in-process model, so the local provider is not held to the deadline.
-    if (provider.kind === 'local')
-        return (await provider.embed([query], 'query'))[0] ?? [];
     try {
         return (await provider.embed([query], 'query', { signal: deadline }))[0] ?? [];
     }
@@ -54,12 +52,12 @@ export async function vectorCandidatesOutside(reads, entries, queryVector, spec)
     return (await reads.nearestEntries(queryVector, stored)).filter((e) => !inPool.has(e.id) && (admit?.(e) ?? true));
 }
 /** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
-export async function resolveVectorArm(query, entries, options) {
+export async function resolveVectorArm(query, entries, source, options) {
     const arm = { entries, addedRows: false, useEmbeddings: false, embeddingIndex: {}, queryVector: [] };
-    if (!options.hippoRoot)
+    if (!source)
         return arm;
     try {
-        await fillVectorArm(arm, query, options.hippoRoot, options);
+        await fillVectorArm(arm, query, source, options);
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
@@ -71,11 +69,10 @@ export async function resolveVectorArm(query, entries, options) {
 async function storedVectorsOf(store, reads, ids) {
     return store.vectorViews ? store.vectorViews.storedVectorViews(ids) : reads.storedVectors(ids);
 }
-async function fillVectorArm(arm, query, root, options) {
+async function fillVectorArm(arm, query, { root, store }, options) {
     const provider = resolveEmbeddingProvider(root);
     if (!provider.isAvailable())
         return;
-    const store = options.store ?? sqliteStore(root);
     const reads = requireVectorReads(store);
     const index = await reads.embeddingIndexState();
     if (indexNeedsRebuild(indexedModel(index), provider.id)) {

package/dist/server/auth.d.ts

@@ -24,6 +24,8 @@ export declare const LIMITER_MAX_KEYS = 10000;
 /** Builds a per-request Context from the Authorization header and remote address; throws HttpError(401) for invalid or missing credentials.
  * Reads the store only for an API-key-shaped Bearer (or any Bearer when no auth resolver is registered), so keyless local requests stay cheap. */
 export declare function buildContextWithAuth(req: IncomingMessage, opts: AuthOpts): Promise<Context>;
+/** The auth check again, uncharged, for a handler that authenticated with requireAuth before a slow body read and must re-check right before it acts. */
+export declare function recheckContextWithAuth(req: IncomingMessage, opts: AuthOpts): Promise<Context>;
 /** Auth check for routes that need no tenant Context (e.g. the MCP transport, which resolves its own root): throws HttpError 401 like buildContextWithAuth.
  * A keyless local request passes only under HIPPO_ALLOW_KEYLESS_LOCAL=1. */
 export declare function requireAuth(req: IncomingMessage, opts: AuthOpts): Promise<void>;

package/dist/server/auth.js

@@ -1,10 +1,11 @@
 // Bearer and loopback auth for the HTTP server.
 import { envAllowKeylessLocal, envRequireAuth } from '../util/env.js';
 import { resolveTenantId } from '../store/tenant.js';
-import { log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { API_KEY_PREFIX, verifyApiKeyCached } from '../store/auth.js';
 import { ownerOrSubject } from '../api/index.js';
-import { HttpError, isCrossSite, isHeaderString, LOOPBACK_HOST_HEADER, MAX_ID_LEN } from '../util/http-util.js';
+import { HttpError, isCrossSite, isHeaderString, LOOPBACK_HOST_HEADER } from '../util/http-util.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { clientLimitKey } from './client-ip.js';
 import { keyCheckBounds } from './key-check-bounds.js';
 import { isJsonString } from '../util/json.js';
@@ -243,11 +244,18 @@ function chargeCaller(tenantId, actor, opts) {
  * Reads the store only for an API-key-shaped Bearer (or any Bearer when no auth resolver is registered), so keyless local requests stay cheap. */
 export async function buildContextWithAuth(req, opts) {
     const id = await checkAuth(req, opts);
-    if (id !== null) {
-        const actor = bearerActor(id);
-        chargeCaller(id.tenantId, actor, opts);
-        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor, store: opts.store };
-    }
+    const ctx = contextFor(id, opts);
+    if (id !== null)
+        chargeCaller(id.tenantId, ctx.actor, opts);
+    return ctx;
+}
+/** The auth check again, uncharged, for a handler that authenticated with requireAuth before a slow body read and must re-check right before it acts. */
+export async function recheckContextWithAuth(req, opts) {
+    return contextFor(await checkAuth(req, opts), opts);
+}
+function contextFor(id, opts) {
+    if (id !== null)
+        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor: bearerActor(id), store: opts.store };
     // The keyless local fallback (HIPPO_ALLOW_KEYLESS_LOCAL=1) is this machine's own user, so it is host admin.
     return {
         hippoRoot: opts.hippoRoot,
@@ -270,6 +278,8 @@ export async function heartbeatVerdict(req, opts) {
         return 'ok';
     }
     catch (err) {
+        if (!(err instanceof HttpError))
+            log.error(`heartbeat auth check failed: ${errorMessage(err)}`, errorFields(err));
         return err instanceof HttpError && err.status < 500 && err.status !== 429 ? 'revoked' : 'unavailable';
     }
 }

package/dist/server/boot.js

@@ -1,9 +1,8 @@
 import { envPort, envRequireAuth, envV1Rps } from '../util/env.js';
-import { existsSync } from 'node:fs';
 import { detectServer, removePidfileIfOwned, writePidfile } from './server-detect.js';
-import { closeHippoDb, getHippoDbPath, isStoreBusy, openHippoDb, outsideRequestStores, outsideSqliteOffLoop, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from '../db/index.js';
-import { startWalCheckpointer } from '../db/wal-checkpointer.js';
-import { requireGroup } from '../store/index.js';
+import { outsideSqliteOffLoop, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from '../db/index.js';
+import { isStoreBusy } from '../store/sqlite/busy.js';
+import { holdSqliteConnection } from '../store/sqlite/held-connection.js';
 import { workerSqliteStore } from '../store/sqlite/worker-store.js';
 import { markSharedStore } from '../core/config.js';
 import { auditWriteFailureCount } from '../store/audit.js';
@@ -12,8 +11,6 @@ import { errorFields, errorMessage, log } from '../util/log.js';
 import { runWithRequestId } from '../util/request-scope.js';
 import { createRateLimiter } from './rate-limit.js';
 import { RecallContractError } from '../api/index.js';
-import { handleSlackEventsWebhook } from '../connectors/slack/webhook.js';
-import { handleGitHubEventsWebhook } from '../connectors/github/webhook.js';
 import { BodyTimeoutError, BodyTooLargeError, closeAfterReply, DeadlineExceededError, HttpError, JSON_HEADERS, sendJson } from '../util/http-util.js';
 import { workerCounts } from '../store/sqlite/executor-counts.js';
 import { isLocalCaller, LIMITER_MAX_KEYS } from './auth.js';
@@ -27,7 +24,8 @@ import { handleMcpPost, handleMcpStream } from './mcp-http.js';
 import { MCP_PROJECT_SCOPED_HEADER } from '../core/project-identity.js';
 import { accessRouteOf, logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError } from './request.js';
 import { createListener, warnIfCleartext } from './tls.js';
-import { assertAddonRoutes, assertPublicJson, dispatchAddonRoute, dispatchPublicJson, dispatchV1Route, isPublicRoute } from './route-table.js';
+import { assertAddonRoutes, assertPublicJson } from './route-checks.js';
+import { dispatchAddonRoute, dispatchPublicJson, dispatchV1Route } from './route-table.js';
 // server.address() returns AddressInfo once a TCP socket is bound; null before
 // listening, a string only for pipe/unix-socket listeners (never used here).
 function isAddressInfo(a) {
@@ -70,13 +68,7 @@ async function handleRequest(req, res, opts, options) {
     res.writeHead(404, JSON_HEADERS);
     res.end(JSON.stringify({ error: 'not found' }));
 }
-const WEBHOOK_GROUPS = ['entryWrites', 'connectorWrites', 'connectorEvents'];
-/** A store missing a group a delivery writes through refuses the webhook up front, so no delivery is acknowledged and then half stored. */
-function requireWebhookGroups(store) {
-    for (const group of WEBHOOK_GROUPS)
-        requireGroup(store, group);
-}
-/** Every route that runs inside a request scope, so it opens each store once: the /v1 table, public JSON, add-on routes, the webhooks and POST /mcp. */
+/** Every route that runs inside a request scope, so it opens each store once: the /v1 table with the webhooks, public JSON, add-on routes and POST /mcp. */
 async function dispatchScopedRoute(r, method, path) {
     if (await dispatchV1Route(r, method, path))
         return true;
@@ -85,26 +77,6 @@ async function dispatchScopedRoute(r, method, path) {
     if (await dispatchAddonRoute(r, method, path))
         return true;
     const { req, res, opts } = r;
-    if (method === 'POST' && path === '/v1/connectors/slack/events') {
-        noteAccess(req, { route: path });
-        // Bearer auth deliberately skipped: this route is in PUBLIC_ROUTES and authenticates via the Slack HMAC signature.
-        if (!isPublicRoute(method, path)) {
-            // Defensive: PUBLIC_ROUTES drift would land here. Fail closed.
-            throw new HttpError(401, 'auth required');
-        }
-        requireWebhookGroups(opts.store);
-        await handleSlackEventsWebhook({ req, res, opts }, opts.store);
-        return true;
-    }
-    if (method === 'POST' && path === '/v1/connectors/github/events') {
-        noteAccess(req, { route: path });
-        if (!isPublicRoute(method, path)) {
-            throw new HttpError(401, 'auth required');
-        }
-        requireWebhookGroups(opts.store);
-        await handleGitHubEventsWebhook({ req, res, opts }, opts.store);
-        return true;
-    }
     // Store-ready: under another store the MCP layer lists and runs only the tools ported to the port.
     if (method === 'POST' && path === '/mcp') {
         noteAccess(req, { route: path });
@@ -204,38 +176,7 @@ function createStoreHolder(hippoRoot, store) {
         log.info(`serve: the '${store.kind}' store serves ${hippoRoot}, so no hippo.db connection is held`);
         return { hold: () => { }, afterResponse: () => { }, release: async () => { } };
     }
-    // Handlers open and close their own connections; while this one is held, none of those closes is SQLite's last,
-    // which checkpoints and deletes the WAL. It opens only once the store exists, so serving never creates one.
-    let heldDb;
-    let checkpointer;
-    let stopHolding = false;
-    const hold = () => {
-        if (heldDb || stopHolding || !existsSync(getHippoDbPath(hippoRoot)))
-            return;
-        try {
-            // The 'finish' listener can fire inside a request scope (closing this connection with the request) and inside a `loop: 'off'` block (refusing the open).
-            // The server's lock wait: this open runs on the event loop, where SQLite's 5 s default and the 30 s journal-mode retry would stall every request.
-            heldDb = outsideSqliteOffLoop(() => outsideRequestStores(() => openHippoDb(hippoRoot, { busyWaitMs: SERVER_DB_WAIT_MS })));
-            checkpointer = startWalCheckpointer(getHippoDbPath(hippoRoot));
-        }
-        catch (err) {
-            stopHolding = true;
-            log.warn(`serve: could not hold a store connection; requests still work, only slower: ${errorMessage(err)}`);
-        }
-    };
-    const afterResponse = () => {
-        hold();
-        checkpointer?.noteResponse();
-    };
-    const release = async () => {
-        stopHolding = true;
-        // The worker's connection closes first, so the held one is SQLite's last and its close checkpoints and deletes the WAL.
-        await checkpointer?.stop();
-        if (heldDb)
-            closeHippoDb(heldDb);
-        heldDb = undefined;
-    };
-    return { hold, afterResponse, release };
+    return holdSqliteConnection(hippoRoot);
 }
 // A plugin's resolver may read hippo.db through this package's synchronous functions, so it runs outside the block of a `loop: 'off'` route.
 function outsideRouteBlock(resolver) {

package/dist/server/client-ip.d.ts

@@ -7,8 +7,6 @@ import type { RateLimiter } from './rate-limit.js';
 export declare function clientIpForRateLimit(req: IncomingMessage): string;
 /** Said once at boot: with no proxy list, a caller that reaches the port without the proxy picks its own bucket by sending the header. */
 export declare function warnIfClientIpHeaderUnpinned(): void;
-/** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
-export declare function subscriberKey(ip: string): string;
 /** The one key every per-address limit and slot count uses, so rotating inside a /64 never buys a fresh bucket. */
 export declare function clientLimitKey(req: IncomingMessage): string;
 export declare function enforceRateLimit(req: IncomingMessage, path: string, limiter?: RateLimiter): void;

package/dist/server/client-ip.js

@@ -57,11 +57,12 @@ export function warnIfClientIpHeaderUnpinned() {
     const header = envClientIpHeader();
     if (!header || trustedProxyList(envTrustedProxies()))
         return;
-    log.warn(`serve: HIPPO_CLIENT_IP_HEADER is ${header} and HIPPO_TRUSTED_PROXIES is unset, so any caller that reaches this port without passing the proxy can send that header and pick its own rate-limit bucket. ` +
+    log.warn(`serve: HIPPO_CLIENT_IP_HEADER is ${header} and HIPPO_TRUSTED_PROXIES is unset, so any caller that reaches this port ` +
+        `without passing the proxy can send that header and pick its own rate-limit bucket. ` +
         "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, so the header is read from the proxy alone.");
 }
 /** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
-export function subscriberKey(ip) {
+function subscriberKey(ip) {
     const bare = ip.split('%')[0];
     if (bare.toLowerCase().startsWith('::ffff:') && isIP(bare.slice(7)) === 4)
         return bare.slice(7);

package/dist/server/deadline.d.ts

@@ -4,8 +4,6 @@ import { RequestDeadline } from '../util/request-scope.js';
 export declare function handlerDeadlineCount(): number;
 /** Whether `res` was answered at its deadline, so whatever its handler does later has no caller. */
 export declare function isAbandoned(res: ServerResponse): boolean;
-/** How long a request may run: 120 s, or HIPPO_REQUEST_DEADLINE_MS, where 0 turns the deadline off. */
-export declare function requestDeadlineMs(): number;
 /** The deadline of `req`, for every /v1 and /mcp route but the two exempt ones. */
 export declare function requestDeadlineFor(req: IncomingMessage): RequestDeadline | undefined;
 /** Calls `reply` when `res` has sent nothing by `deadline`. A store call still in flight answers first, since only the store knows what became of a write. */

package/dist/server/deadline.js

@@ -1,6 +1,4 @@
-import { envRequestDeadlineMs } from '../util/env.js';
-import { RequestDeadline } from '../util/request-scope.js';
-const DEFAULT_REQUEST_DEADLINE_MS = 120_000;
+import { RequestDeadline, requestDeadlineMs } from '../util/request-scope.js';
 // Each has a deadline of its own kind: sleep stops its child process, and the stream is meant to stay open.
 const EXEMPT = new Set(['POST /v1/sleep', 'GET /mcp/stream']);
 const abandoned = new WeakSet();
@@ -13,10 +11,6 @@ export function handlerDeadlineCount() {
 export function isAbandoned(res) {
     return abandoned.has(res);
 }
-/** How long a request may run: 120 s, or HIPPO_REQUEST_DEADLINE_MS, where 0 turns the deadline off. */
-export function requestDeadlineMs() {
-    return envRequestDeadlineMs() ?? DEFAULT_REQUEST_DEADLINE_MS;
-}
 /** The deadline of `req`, for every /v1 and /mcp route but the two exempt ones. */
 export function requestDeadlineFor(req) {
     const ms = requestDeadlineMs();

package/dist/server/defaults.d.ts

@@ -1,3 +1,4 @@
 export declare const DEFAULT_SERVER_PORT = 6789;
 export declare const DEFAULT_SERVER_HOST = "127.0.0.1";
+export declare const DEFAULT_DASHBOARD_PORT = 3333;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/server/defaults.js

@@ -1,4 +1,5 @@
 // `hippo serve` reads these without loading the server, so the CLI and serve() cannot disagree on a default.
 export const DEFAULT_SERVER_PORT = 6789;
 export const DEFAULT_SERVER_HOST = '127.0.0.1';
+export const DEFAULT_DASHBOARD_PORT = 3333;
 //# sourceMappingURL=defaults.js.map

package/dist/server/mcp-http.js

@@ -1,28 +1,29 @@
 // MCP over HTTP: POST /mcp and the GET /mcp/stream SSE keepalive.
 import { envMcpSseHeartbeatMs, envMcpSseMaxAgeSec, envMcpSseMaxStreams } from '../util/env.js';
-import { createHash } from 'node:crypto';
 import { isSharedStore } from '../core/config.js';
 import { handleMcpRequest, mcpErrorResponse } from '../mcp/server.js';
 import { HttpError, readBody, sendJson } from '../util/http-util.js';
+import { log } from '../util/log.js';
 import { assertCallerProject } from '../core/project-identity.js';
 import { buildContextWithAuth, heartbeatVerdict, readAuthHeader, requireAuth } from './auth.js';
-import { clientLimitKey, subscriberKey } from './client-ip.js';
+import { clientLimitKey } 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;
+import { blockHash } from '../util/token-text.js';
+import { consolidateInChild } from './sleep-offload.js';
+const DEFAULT_SSE_HEARTBEAT_MS = 60_000;
 const DEFAULT_SSE_MAX_AGE_SEC = 3600;
 /** Per-client key for MCP state isolation under HTTP-MCP (scopes `lastRecalledIds`): sha256 of the token (16 hex chars, so the raw bearer is never logged)
- * plus remoteAddress, so clients sharing a key stay separable; 'noauth' covers loopback no-auth, which is single-host single-user. */
+ * plus the client address the rate limiter keys on, so clients sharing a key stay separable behind a trusted proxy too; 'noauth' covers loopback no-auth. */
 function buildMcpClientKey(req) {
     const auth = readAuthHeader(req);
     const tokenHash = auth.kind === 'bearer'
-        ? createHash('sha256').update(auth.token).digest('hex').slice(0, FINGERPRINT_HEX_CHARS)
+        ? blockHash(auth.token)
         : 'noauth';
-    const addr = subscriberKey(req.socket.remoteAddress ?? 'unknown');
-    return `http:${tokenHash}:${addr}`;
+    return `http:${tokenHash}:${clientLimitKey(req)}`;
 }
-// MCP-over-HTTP/SSE: POST /mcp answers a JSON-RPC request synchronously; GET /mcp/stream is a keepalive-only SSE stream (`: ping` every 30s) in v1.
+// MCP-over-HTTP/SSE: POST /mcp answers a JSON-RPC request synchronously; GET /mcp/stream is a keepalive-only SSE stream
+// (`: ping` every DEFAULT_SSE_HEARTBEAT_MS, 60 s) in v1.
 // Both dispatch to handleMcpRequest as stdio does. Auth matches /v1/* (Bearer via `requireAuth`, loopback fallback); SSE is checked once at stream-open.
 // Percent-encoded by the client, so any lowercase Unicode name fits a Latin-1 header.
 const HEADER_PIECE = /^[A-Za-z0-9\-_.!~*'()%]+$/;
@@ -70,6 +71,7 @@ function mcpContextFor(ctx, clientKey, autoSleep, project) {
         clientKey,
         store: ctx.store,
         autoSleep,
+        autoSleepRunner: consolidateInChild,
     };
     if (project !== undefined)
         mcpCtx.project = project;
@@ -100,7 +102,8 @@ 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);
+        const tool = rpcReq.params?.name;
+        mcpRes = mcpErrorResponse(rpcReq.id, err, undefined, isJsonString(tool) ? `${rpcReq.method} ${tool.slice(0, 128)}` : rpcReq.method);
     }
     if (mcpRes === null) {
         // Notification — no body, 202 Accepted.
@@ -116,7 +119,7 @@ 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, FINGERPRINT_HEX_CHARS)}`;
+        return `key:${blockHash(auth.token)}`;
     return `ip:${clientLimitKey(req)}`;
 }
 /** Takes a stream slot or throws 429; the slot is released once, when the response closes. */
@@ -180,6 +183,8 @@ function keepStreamAlive(req, res, opts) {
         checking = true;
         void heartbeatVerdict(req, opts).then((verdict) => {
             checking = false;
+            if (!closed && verdict === 'unavailable')
+                log.warn('heartbeat tick skipped: auth check unavailable');
             if (closed || verdict === 'unavailable')
                 return;
             if (verdict === 'revoked') {

package/dist/server/request.js

@@ -1,7 +1,9 @@
 import { randomUUID } from 'node:crypto';
-import { isStoreBusy, STORE_BUSY_MESSAGE } from '../db/index.js';
+import { STORE_BUSY_MESSAGE } from '../store/port.js';
+import { isStoreBusy } from '../store/sqlite/busy.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
-import { HttpError, mapApiError, sendJson } from '../util/http-util.js';
+import { mapApiError } from '../api/error-reply.js';
+import { HttpError, 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. */
@@ -18,6 +20,9 @@ export function logRequestFailure(req, err, status) {
         log.warn(line, { status });
     else if (status >= 500 && status !== 501)
         log.error(line, { status, ...errorFields(err) });
+    // A failed login is the one 4xx an operator needs by default; the id (never the credential) is stamped from the request scope.
+    else if (status === 401 || status === 403)
+        log.warn(line, { status });
     else
         log.info(line, { status });
 }

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

@@ -0,0 +1,7 @@
+import type { JsonValue } from '../util/json.js';
+import type { AddonRoute } from './types.js';
+/** 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>;
+//# sourceMappingURL=route-checks.d.ts.map

package/dist/server/route-checks.js

@@ -0,0 +1,42 @@
+import { V1_ROUTES, routeMatches } from './route-table.js';
+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 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;
+}
+//# sourceMappingURL=route-checks.js.map

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

@@ -1,15 +1,16 @@
-import type { AddonRoute, ResolvedServeOpts, RouteRequest } from './types.js';
-import type { JsonValue } from '../util/json.js';
-export declare function isPublicRoute(method: string, path: string): boolean;
+import type { Route, RouteRequest } from './types.js';
+/** The /v1 routes in dispatch order; the first entry whose method and path match handles the request. Each row's `auth` is what the
+ *  dispatch gate proves before its handler runs, so a handler never checks the caller itself. */
+export declare const V1_ROUTES: readonly Route[];
+/** The route's run for this request, gate first, 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. */
+export declare function routeMatches(route: Route, method: string, path: string): ((r: RouteRequest) => Promise<void>) | 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. */
+export declare function routeLabel(route: Route): string;
 /** 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