hippo-memory 1.72.0 → 2.0.0

package/dist/mcp/request.js

@@ -1,12 +1,14 @@
 // Transport-agnostic request handling: tool dispatch table, tool execution and the JSON-RPC method switch.
 import { errorMessage, log } from '../util/log.js';
+import { currentSignal } from '../util/request-scope.js';
 import { STORE_NOT_PORTED_MESSAGE } from '../util/http-util.js';
 import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
 import { loadConfig } from '../core/config.js';
 import { resolveTenantId } from '../store/tenant.js';
 import { runWithRequestStores } from '../db/index.js';
 import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
-import { hasGroup, storeFor } from '../store/index.js';
+import { hasGroup } from '../store/index.js';
+import { storeFor } from '../store/sqlite/store.js';
 import { estimateTokens } from '../util/token-text.js';
 import { PACKAGE_VERSION } from '../util/version.js';
 import { validateToolArgs } from './tool-args.js';
@@ -62,20 +64,15 @@ const TOOL_HANDLERS = new Map([
     ['hippo_outcome', { handler: runOutcomeTool, storeReady: 'entryWrites' }],
     ['hippo_context', { handler: runContextTool, storeReady: 'contextReads' }],
     ['hippo_status', { handler: runStatusTool }],
-    ['hippo_learn', { handler: runLearnTool }],
+    ['hippo_learn', { handler: runLearnTool, storeReady: 'lessonWrites' }],
     ['hippo_conflicts', { handler: runConflictsTool }],
     ['hippo_resolve', { handler: runResolveTool }],
     ['hippo_share', { handler: runShareTool }],
     ['hippo_peers', { handler: runPeersTool }],
 ]);
-/** The served store when it is not hippo.db, else null. */
-function otherStore(ctx) {
-    const store = ctx?.store;
-    return store !== undefined && store.kind !== 'sqlite' ? store : null;
-}
+/** Stdio serves no store and runs every tool on the folder's hippo.db. */
 function runsOn(store, toolName) {
-    const group = TOOL_HANDLERS.get(toolName)?.storeReady;
-    return group !== undefined && hasGroup(store, group);
+    return store === undefined || hasGroup(store, TOOL_HANDLERS.get(toolName)?.storeReady ?? 'localFiles');
 }
 async function executeTool(name, args, ctx) {
     // With a transport context (HTTP), trust it: hippoRoot comes from the server's bound opts and tenantId from the Bearer (or loopback fallback).
@@ -100,6 +97,17 @@ function invalidArgs(id, toolName, problems) {
         result: { content: [{ type: 'text', text: `Invalid arguments for ${toolName}: ${problems.join('; ')}` }], isError: true },
     };
 }
+/** One handle per store for the tool and its ledger row; stdio interleaves calls, so each gets its own scope.
+ *  SHORTCUT: the deadline stops a call only between these steps, not a store read or fetch already running; thread the signal into them. */
+function runToolScoped(toolName, args, ctx) {
+    return runWithRequestStores(async () => {
+        currentSignal()?.throwIfAborted();
+        const text = await executeTool(toolName, args, ctx);
+        currentSignal()?.throwIfAborted();
+        await recordMcpTokens(toolName, text, ctx);
+        return text;
+    });
+}
 async function callTool(id, params, ctx) {
     const nameValue = params?.name;
     const toolName = isJsonString(nameValue) ? nameValue : '';
@@ -108,8 +116,7 @@ async function callTool(id, params, ctx) {
         return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${toolName.slice(0, 128)}` } };
     }
     // The same refusal a ported tool gives when it reaches hippo.db, so a client handles one shape.
-    const other = otherStore(ctx);
-    if (other && !runsOn(other, toolName)) {
+    if (!runsOn(ctx?.store, toolName)) {
         return { jsonrpc: '2.0', id, error: { code: -32603, message: STORE_NOT_PORTED_MESSAGE } };
     }
     const refusal = sharedStoreRefusal(toolName, ctx);
@@ -125,12 +132,7 @@ async function callTool(id, params, ctx) {
         return invalidArgs(id, toolName, problems);
     let output;
     try {
-        // One handle per store for the tool and its ledger row; stdio interleaves calls, so each gets its own scope.
-        output = await runWithRequestStores(async () => {
-            const text = await executeTool(toolName, toolArgs, ctx);
-            await recordMcpTokens(toolName, text, ctx);
-            return text;
-        });
+        output = await runToolScoped(toolName, toolArgs, ctx);
     }
     catch (err) {
         if (!(err instanceof RecallRequestError))
@@ -163,8 +165,7 @@ export async function handleMcpRequest(req, ctx) {
         case 'notifications/initialized':
             return null;
         case 'tools/list': {
-            const other = otherStore(ctx);
-            return { jsonrpc: '2.0', id, result: { tools: other ? TOOLS.filter((t) => runsOn(other, t.name)) : TOOLS } };
+            return { jsonrpc: '2.0', id, result: { tools: TOOLS.filter((t) => runsOn(ctx?.store, t.name)) } };
         }
         case 'tools/call':
             return callTool(id, params, ctx);

package/dist/mcp/stdio.js

@@ -75,7 +75,7 @@ function callName(req) {
 }
 /** Answers `req` with one timeout error at the deadline a served request has. The returned function stops the timer and says whether that
  * answer went out, so a later reply is dropped. */
-function watchDeadline(req, owedReply) {
+function watchDeadline(req, owedReply, abort) {
     const ms = requestDeadlineMs();
     if (ms === 0)
         return () => false;
@@ -83,7 +83,8 @@ function watchDeadline(req, owedReply) {
     const timer = setTimeout(() => {
         expired = true;
         const name = callName(req);
-        log.warn(`mcp: ${name} did not answer within ${ms} ms; it keeps running and its reply will be dropped`, { method: req.method });
+        log.warn(`mcp: ${name} did not answer within ${ms} ms; its next step is cancelled and its reply will be dropped`, { method: req.method });
+        abort.abort(new DOMException(`${name} did not finish within ${ms} ms`, 'TimeoutError'));
         if (!owedReply)
             return;
         const requestId = currentRequestId();
@@ -100,7 +101,7 @@ function watchDeadline(req, owedReply) {
         return expired;
     };
 }
-function dispatch(body) {
+function dispatch(body, abort) {
     let parsed;
     try {
         parsed = JSON.parse(body);
@@ -116,17 +117,19 @@ function dispatch(body) {
     }
     const req = parsed;
     if (req.method.startsWith('notifications/')) {
-        const stopWatching = watchDeadline(req, false);
+        const stopWatching = watchDeadline(req, false, abort);
         track(req.method, handleMcpRequest(req).then(() => { }).catch((err) => {
             log.error(`mcp notification ${req.method} failed: ${errorMessage(err)}`, errorFields(err));
         }).finally(stopWatching));
         return;
     }
     // A frame with no id is a notification under any method name, and JSON-RPC forbids answering one.
-    const timedOut = watchDeadline(req, isJsonString(req.id) || isJsonNumber(req.id));
+    const timedOut = watchDeadline(req, isJsonString(req.id) || isJsonNumber(req.id), abort);
     track(req.method, handleMcpRequest(req).then((resp) => { if (!timedOut() && resp)
         send(resp); }).catch((err) => {
-        if (timedOut())
+        if (timedOut() && err instanceof DOMException && err.name === 'TimeoutError')
+            log.debug(`mcp: ${callName(req)} stopped at its deadline`);
+        else if (timedOut())
             log.error(`mcp: ${callName(req)} failed after its timeout reply: ${errorMessage(err)}`, errorFields(err));
         else
             send(mcpErrorResponse(req.id, err, undefined, callName(req)));
@@ -158,8 +161,10 @@ export function startStdioLoop() {
                 continue;
             }
             // One id per frame, so the error reply and every line logged for the call name the same request.
-            if (result.kind === 'message')
-                runWithRequestId(randomUUID(), () => dispatch(result.body));
+            if (result.kind === 'message') {
+                const abort = new AbortController();
+                runWithRequestId(randomUUID(), () => dispatch(result.body, abort), undefined, abort.signal);
+            }
         }
         pending = buffer.length > 0 ? [buffer] : [];
         pendingBytes = buffer.length;

package/dist/rerankers/cross-encoder.js

@@ -48,10 +48,12 @@ function identityOrder(head) {
     }));
 }
 async function scoreHead(pipe, query, head) {
+    let succeeded = 0;
     const scored = await Promise.all(head.map(async (r, i) => {
         let ceScore;
         try {
             ceScore = await pipe(query, r.entry.content);
+            succeeded++;
         }
         catch (err) {
             // One bad inference must not sink the whole pass.
@@ -69,7 +71,7 @@ async function scoreHead(pipe, query, head) {
     // relevance order, never an arbitrary content order.
     scored.sort((a, b) => compareScoresDesc(a.rerankScore, b.rerankScore));
     scored.forEach((r, i) => (r.postRerankRank = i + 1));
-    return scored;
+    return { results: scored, succeeded };
 }
 /** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. Each instance owns its model and outage warning. */
 export function createCrossEncoderReranker(importModule = importTransformers) {
@@ -88,8 +90,13 @@ export function createCrossEncoderReranker(importModule = importTransformers) {
             outage.failed(errorMessage(err), errorFields(err));
             return identityOrder(head);
         }
-        outage.answered();
-        return scoreHead(pipe, query, head);
+        const { results: scored, succeeded } = await scoreHead(pipe, query, head);
+        // A loaded model whose every call throws is as dead as one that never loaded.
+        if (head.length > 0 && succeeded === 0)
+            outage.failed('every inference failed');
+        else
+            outage.answered();
+        return scored;
     };
 }
 //# sourceMappingURL=cross-encoder.js.map

package/dist/search/embed-memories.d.ts

@@ -1,8 +1,11 @@
 import type { MemoryEntry } from '../core/memory.js';
 import { type EmbeddingProvider } from '../embeddings/provider.js';
 import { type HippoStore } from '../store/port.js';
-/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
-export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<void>;
+/** `off` is a provider that is disabled or not installed, which is a choice; `failed` is a memory that stays out of the vector index. */
+export type EmbedOutcome = 'indexed' | 'off' | 'failed';
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db.
+ *  Resolves whatever fails, so a caller that fires and forgets stays safe; the outcome says whether the memory reached the index. */
+export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<EmbedOutcome>;
 /** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
  *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
 export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider, store?: HippoStore): Promise<number>;

package/dist/search/embed-memories.js

@@ -4,7 +4,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { loadConfig } from '../core/config.js';
-import { initializeParticle } from '../db/physics-state.js';
+import { initializeParticle } from '../core/physics.js';
 import { resolveEmbeddingProvider } from '../embeddings/provider.js';
 import { embeddingIndexIdentity, embeddingInputText, embeddingModelRequiresReindex, indexNeedsRebuild, saveStoredEmbeddingModel, } from '../store/embeddings/index.js';
 import { loadAllEntryIds, loadEntriesByIds } from '../store/entry-reads.js';
@@ -191,7 +191,7 @@ async function writeVectorPage(writes, write, page, vectors, withParticles) {
         if (!vector || vector.length === 0)
             return noteSkippedEmbedding(entry.id);
         const row = withParticles ? { memoryId: entry.id, vector, particle: initializeParticle(entry, vector) } : { memoryId: entry.id, vector };
-        byTenant.set(entry.tenantId, [...(byTenant.get(entry.tenantId) ?? []), row]);
+        byTenant.set(entry.tenant_id, [...(byTenant.get(entry.tenant_id) ?? []), row]);
     });
     let written = 0;
     for (const [tenantId, rows] of byTenant) {
@@ -237,15 +237,20 @@ function embedMemoryInStore(store, provider, entry) {
                 || (await writeVectorPage(writes, { model, replaceIndex: false }, [entry], await provider.embed([embeddingInputText(entry)], 'passage'), true)).modelMismatch;
             if (refused)
                 warnEmbedFailureOnce('index', OTHER_MODEL_INDEX);
+            return refused ? 'failed' : 'indexed';
         }
         catch (err) {
             warnEmbedFailureOnce(provider.kind, errorMessage(err), err);
+            return 'failed';
         }
     }).catch((err) => {
         log.warn(`skipped embedding ${entry.id} (${errorMessage(err)})`);
+        return 'failed';
     });
 }
-/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
+const INLINE_REINDEX_MAX_ROWS = 256;
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db.
+ *  Resolves whatever fails, so a caller that fires and forgets stays safe; the outcome says whether the memory reached the index. */
 export async function embedMemory(hippoRoot, entry, model, store) {
     let provider;
     try {
@@ -254,38 +259,45 @@ export async function embedMemory(hippoRoot, entry, model, store) {
     catch (err) {
         // Callers fire and forget, so this must resolve: a bad config warns once instead of rejecting.
         warnEmbedFailureOnce('config', errorMessage(err), err);
-        return;
+        return 'failed';
     }
     if (!provider.isAvailable())
-        return;
+        return 'off';
     if (store)
         return embedMemoryInStore(store, provider, entry);
-    return withEmbedLock(hippoRoot, async () => {
-        // Best-effort: an embedding failure (API down, bad key, 5xx) must not reject the caller's write; the existing index is left as-is.
-        // Failures surface on the explicit `hippo embed` / `embedAll` path.
-        try {
-            const identity = provider.id;
-            if (embeddingModelRequiresReindex(hippoRoot, identity)) {
-                await rebuildIndexForProvider(hippoRoot, provider);
-                return;
-            }
-            const text = embeddingInputText(entry);
-            const [vector] = await provider.embed([text], 'passage');
-            if (!vector || vector.length === 0)
-                return;
-            saveStoredVectors(hippoRoot, [[entry.id, vector]], embeddingIndexIdentity(identity));
-            saveStoredEmbeddingModel(hippoRoot, identity);
-            // Initialize physics state for this memory
-            initializePhysicsIfMissing(hippoRoot, entry, vector);
-        }
-        catch (err) {
-            // Provider failure (API down / bad key). Best-effort: leave the index as-is, but say so once.
-            warnEmbedFailureOnce(provider.kind, errorMessage(err), err);
-        }
-    }).catch((err) => {
+    return withEmbedLock(hippoRoot, () => embedMemoryLocked(hippoRoot, provider, entry)).catch((err) => {
         log.warn(`skipped embedding ${entry.id} (${errorMessage(err)}); run 'hippo embed' to backfill`);
+        return 'failed';
     });
 }
+/** Best-effort: an embedding failure (API down, bad key, 5xx) must not reject the caller's write; the existing index is left as-is.
+ *  Failures surface on the explicit `hippo embed` / `embedAll` path. */
+async function embedMemoryLocked(hippoRoot, provider, entry) {
+    try {
+        const identity = provider.id;
+        if (embeddingModelRequiresReindex(hippoRoot, identity)) {
+            // A fire-and-forget write heals a small index inline; a large one is left to `hippo embed`, so no write holds the lock for a whole-store embed.
+            if (loadAllEntryIds(hippoRoot).length > INLINE_REINDEX_MAX_ROWS) {
+                warnEmbedFailureOnce('index', OTHER_MODEL_INDEX);
+                return 'failed';
+            }
+            await rebuildIndexForProvider(hippoRoot, provider);
+            return 'indexed';
+        }
+        const [vector] = await provider.embed([embeddingInputText(entry)], 'passage');
+        if (!vector || vector.length === 0)
+            return 'failed';
+        saveStoredVectors(hippoRoot, [[entry.id, vector]], embeddingIndexIdentity(identity));
+        saveStoredEmbeddingModel(hippoRoot, identity);
+        initializePhysicsIfMissing(hippoRoot, entry, vector);
+        return 'indexed';
+    }
+    catch (err) {
+        // Provider failure (API down / bad key). Best-effort: leave the index as-is, but say so once.
+        warnEmbedFailureOnce(provider.kind, errorMessage(err), err);
+        return 'failed';
+    }
+}
 // Every page is embedded before one transaction replaces the index, and the identity is saved only after that: a provider failure or a crash
 // at any earlier point leaves the old identity, so embeddingModelRequiresReindex has the next run rebuild from the start.
 async function rebuildIndexForProvider(hippoRoot, provider) {

package/dist/search/engine.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryEntry } from '../core/memory.js';
+import type { PhysicsConfig } from '../core/physics-config.js';
+import type { SearchResult } from '../core/search-types.js';
+import { type HybridSearchOptions } from './hybrid.js';
+import type { VectorSource } from './vector.js';
+/** Physics scoring when `physics` holds its config, hybrid otherwise, both on the store `source` names; each caller keeps its own options. */
+export declare function searchByEngine(source: VectorSource, query: string, pool: MemoryEntry[], physics: PhysicsConfig | null, options: Omit<HybridSearchOptions, 'hippoRoot' | 'store'>): Promise<SearchResult[]>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/search/engine.js

@@ -0,0 +1,10 @@
+// The one search-engine choice every ranker over a candidate pool makes: recall's band, MCP's wide list, the CLI core and context.
+import { hybridSearch } from './hybrid.js';
+import { physicsSearchIn } from './physics-search.js';
+/** Physics scoring when `physics` holds its config, hybrid otherwise, both on the store `source` names; each caller keeps its own options. */
+export function searchByEngine(source, query, pool, physics, options) {
+    return physics
+        ? physicsSearchIn(source, query, pool, { ...options, physicsConfig: physics })
+        : hybridSearch(query, pool, { ...options, hippoRoot: source.root, store: source.store });
+}
+//# sourceMappingURL=engine.js.map

package/dist/search/vector.js

@@ -5,7 +5,7 @@ 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 } from '../store/index.js';
+import { hasGroup, 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.
@@ -33,12 +33,12 @@ export async function embedQueryBy(deadline, provider, query) {
 function warnBm25Fallback(reason, detail) {
     log.once(`search.bm25-fallback.${reason}`, 'warn', `hybrid search fell back to BM25 only: ${redactSecretsStrict(detail)}`);
 }
-function reindexHint(storeKind) {
+function reindexHint(store) {
     const why = 'the embedding index was built by another model or is being rebuilt';
     // `hippo embed` writes only hippo.db, so another store gets its vectors by a rebuild from it.
-    return storeKind === 'sqlite'
+    return hasGroup(store, 'localFiles')
         ? `${why}; run 'hippo embed'`
-        : `${why}; run 'hippo embed' on the SQLite store, then rebuild the '${storeKind}' database from it`;
+        : `${why}; run 'hippo embed' on the SQLite store, then rebuild the '${store.kind}' database from it`;
 }
 /** The store's vector reads; a store without them answers 501, as any unported path does. */
 export function requireVectorReads(store) {
@@ -76,7 +76,7 @@ async function fillVectorArm(arm, query, { root, store }, options) {
     const reads = requireVectorReads(store);
     const index = await reads.embeddingIndexState();
     if (indexNeedsRebuild(indexedModel(index), provider.id)) {
-        warnBm25Fallback('reindex', reindexHint(store.kind));
+        warnBm25Fallback('reindex', reindexHint(store));
         return;
     }
     const spec = options.vectorCandidates;

package/dist/server/auth.d.ts

@@ -16,7 +16,7 @@ type AuthHeader = {
     token: string;
 };
 export declare function readAuthHeader(req: IncomingMessage): AuthHeader;
-type AuthOpts = Pick<ResolvedServeOpts, 'hippoRoot' | 'authResolver' | 'authResolverTimeoutMs' | 'store' | 'callerLimiter'> & Partial<Pick<ResolvedServeOpts, 'failedAuthLimiter'>>;
+type AuthOpts = Pick<ResolvedServeOpts, 'hippoRoot' | 'authResolver' | 'authResolverTimeoutMs' | 'store' | 'callerLimiter'> & Partial<Pick<ResolvedServeOpts, 'failedAuthLimiter' | 'keylessLocalRole'>>;
 /** Add-ons call this to refuse a subject that would collide with a built-in actor. */
 export declare function isReservedActor(subject: string): boolean;
 /** Key cap for every serve() bucket, shared by the warn map so it never tracks more callers than the buckets do. */

package/dist/server/auth.js

@@ -1,5 +1,5 @@
 // Bearer and loopback auth for the HTTP server.
-import { envAllowKeylessLocal, envRequireAuth } from '../util/env.js';
+import { envAllowKeylessLocal, envKeylessLocalRole, envRequireAuth } from '../util/env.js';
 import { resolveTenantId } from '../store/tenant.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { API_KEY_PREFIX, verifyApiKeyCached } from '../store/auth.js';
@@ -253,16 +253,15 @@ export async function buildContextWithAuth(req, opts) {
 export async function recheckContextWithAuth(req, opts) {
     return contextFor(await checkAuth(req, opts), opts);
 }
+/** The keyless local caller: any process on this machine can reach loopback, so it is a member unless the operator names admin. */
+function keylessLocalActor(opts) {
+    const role = opts.keylessLocalRole ?? envKeylessLocalRole();
+    return role === 'admin' ? { subject: 'localhost:cli', role: 'admin', hostAdmin: true } : { subject: 'localhost:cli', role: 'member' };
+}
 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,
-        tenantId: resolveTenantId({}),
-        actor: { subject: 'localhost:cli', role: 'admin', hostAdmin: true },
-        store: opts.store,
-    };
+    return { hippoRoot: opts.hippoRoot, tenantId: resolveTenantId({}), actor: keylessLocalActor(opts), store: opts.store };
 }
 /** 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. */

package/dist/server/boot.d.ts

@@ -1,5 +1,6 @@
 import type { ServeOpts, ServerHandle } from './types.js';
-/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses non-loopback hosts unless HIPPO_REQUIRE_AUTH=1.
+/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses a non-loopback host unless HIPPO_REQUIRE_AUTH=1 and
+ * either `tls` or allowCleartext is given, and refuses HIPPO_CLIENT_IP_HEADER without HIPPO_TRUSTED_PROXIES.
  * Use port: 0 in tests for an ephemeral port. See docs/ARCHITECTURE.md#srcserverbootts. */
 export declare function serve(opts: ServeOpts): Promise<ServerHandle>;
 //# sourceMappingURL=boot.d.ts.map

package/dist/server/boot.js

@@ -1,6 +1,7 @@
-import { envPort, envRequireAuth, envV1Rps } from '../util/env.js';
+import { envAllowCleartext, envCallerRps, envPort, envRequireAuth, envV1Rps } from '../util/env.js';
 import { detectServer, removePidfileIfOwned, writePidfile } from './server-detect.js';
 import { outsideSqliteOffLoop, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from '../db/index.js';
+import { hasGroup } from '../store/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';
@@ -14,7 +15,7 @@ import { RecallContractError } from '../api/index.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';
-import { enforceRateLimit, warnIfClientIpHeaderUnpinned } from './client-ip.js';
+import { assertClientIpHeaderPinned, enforceRateLimit } from './client-ip.js';
 import { answerAtDeadline, handlerDeadlineCount, isAbandoned, requestDeadlineFor } from './deadline.js';
 import { DEFAULT_SHUTDOWN_DRAIN_MS, drainAndClose, setKeepAliveTimeouts, shutdownBoundMs } from './lifecycle.js';
 import { readyProbeFor } from './ready.js';
@@ -23,7 +24,7 @@ import { installCrashHandlers, installSignalHandlers } from '../util/crash-handl
 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 { assertTlsOrCleartextAllowed, createListener } from './tls.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
@@ -156,27 +157,37 @@ function assertRateLimitSpec(name, { ratePerSec, burst }) {
     if (!Number.isFinite(burst) || burst < 1)
         throw new Error(`rateLimits.${name}.burst must be a finite number of at least 1`);
 }
+const DEFAULT_CALLER_RPS = 20;
+/** The per-caller spec when serve() names none: HIPPO_CALLER_RPS (0 is off), else 20 per second with a burst of twice that. */
+function defaultCallerSpec() {
+    const raw = envCallerRps();
+    const rps = raw === undefined ? DEFAULT_CALLER_RPS : Number(raw);
+    // A typo must not switch the limit off, so only an explicit 0 does.
+    if (!Number.isFinite(rps) || rps < 0)
+        throw new Error(`HIPPO_CALLER_RPS must be a number of at least 0 (0 turns the per-caller limit off), not '${raw}'`);
+    return rps === 0 ? 'off' : { ratePerSec: rps, burst: Math.max(1, rps * 2) };
+}
 /** Refuses a bad spec at boot, since a NaN or zero rate would otherwise turn a bucket off or refuse every request. */
 function bootLimiters(rateLimits) {
-    const { perCaller, perAddress, failedAuthPerAddress = DEFAULT_FAILED_AUTH } = rateLimits ?? {};
-    if (perCaller !== undefined)
+    const { perCaller = defaultCallerSpec(), perAddress, failedAuthPerAddress = DEFAULT_FAILED_AUTH } = rateLimits ?? {};
+    if (perCaller !== 'off')
         assertRateLimitSpec('perCaller', perCaller);
     if (perAddress !== undefined && perAddress !== 'off')
         assertRateLimitSpec('perAddress', perAddress);
     assertRateLimitSpec('failedAuthPerAddress', failedAuthPerAddress);
-    warnIfClientIpHeaderUnpinned();
+    assertClientIpHeaderPinned();
     return {
         perAddress: bootRateLimiter(perAddress),
-        callerLimiter: perCaller === undefined ? undefined : limiterFor(perCaller),
+        callerLimiter: perCaller === 'off' ? undefined : limiterFor(perCaller),
         failedAuthLimiter: limiterFor(failedAuthPerAddress),
     };
 }
 function createStoreHolder(hippoRoot, store) {
-    if (store.kind !== 'sqlite') {
-        log.info(`serve: the '${store.kind}' store serves ${hippoRoot}, so no hippo.db connection is held`);
-        return { hold: () => { }, afterResponse: () => { }, release: async () => { } };
-    }
-    return holdSqliteConnection(hippoRoot);
+    if (hasGroup(store, 'localFiles'))
+        return holdSqliteConnection(hippoRoot);
+    log.info(`serve: the '${store.kind}' store serves ${hippoRoot}, so no hippo.db connection is held`);
+    // A missed port under another store would otherwise create and write a hippo.db that store never reads.
+    return { hold: () => { }, afterResponse: () => { }, release: async () => { }, runRequest: (run) => withSqliteBlocked(store.kind, run) };
 }
 // 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) {
@@ -287,7 +298,8 @@ function exitOnSignalOrCrash(stop, drainMs) {
     installSignalHandlers('serve', shutdown);
     installCrashHandlers('serve', shutdown);
 }
-/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses non-loopback hosts unless HIPPO_REQUIRE_AUTH=1.
+/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses a non-loopback host unless HIPPO_REQUIRE_AUTH=1 and
+ * either `tls` or allowCleartext is given, and refuses HIPPO_CLIENT_IP_HEADER without HIPPO_TRUSTED_PROXIES.
  * Use port: 0 in tests for an ephemeral port. See docs/ARCHITECTURE.md#srcserverbootts. */
 export async function serve(opts) {
     const host = opts.host ?? DEFAULT_SERVER_HOST;
@@ -296,6 +308,7 @@ export async function serve(opts) {
     const publicJsonBodies = assertPublicJson(opts.publicJson ?? {});
     const limiters = bootLimiters(opts.rateLimits);
     assertBindable(host);
+    assertTlsOrCleartextAllowed(host, opts.tls, LOOPBACK_HOSTS, opts.allowCleartext ?? envAllowCleartext());
     await assertNoLiveServer(opts.hippoRoot);
     // Single source of truth for the start time: returned by GET /health and written into the pidfile, so detectServer can prove a pid-reusing impostor is not
     // this server.
@@ -304,7 +317,7 @@ export async function serve(opts) {
     const streamSlots = new Map();
     const served = servedOptsFor(opts, routes, publicJsonBodies, limiters);
     // A store other than hippo.db is a team's central server, so its folder's config.json must not decide shared-ness.
-    if (served.store.kind !== 'sqlite')
+    if (!hasGroup(served.store, 'localFiles'))
         markSharedStore(opts.hippoRoot);
     const holder = createStoreHolder(opts.hippoRoot, served.store);
     const inflight = new Set();
@@ -343,14 +356,11 @@ function servedOptsFor(opts, routes, publicJsonBodies, { callerLimiter, failedAu
     };
 }
 function acceptingServer(served, holder, inflight, options) {
-    const { kind } = served.store;
     return createListener(served.tls, (req, res) => {
         res.once('finish', holder.afterResponse);
         inflight.add(res);
         res.once('close', () => inflight.delete(res));
-        const run = () => handleRequest(req, res, served, options);
-        // A missed port under another store would otherwise create and write a hippo.db that store never reads.
-        answerRequest(req, res, () => (kind === 'sqlite' ? run() : withSqliteBlocked(kind, run)), served.slowRequestWarnMs);
+        answerRequest(req, res, () => holder.runRequest(() => handleRequest(req, res, served, options)), served.slowRequestWarnMs);
     });
 }
 async function listenAndDescribe(server, port, host, tls) {
@@ -362,7 +372,6 @@ async function listenAndDescribe(server, port, host, tls) {
     const addressInfo = address;
     const actualPort = addressInfo.port;
     const url = `${tls ? 'https' : 'http'}://${host.includes(':') ? `[${host}]` : host}:${actualPort}`;
-    warnIfCleartext(host, tls, LOOPBACK_HOSTS);
     return { port: actualPort, url };
 }
 async function stopListening(opts, server, inflight, startedAt) {

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

@@ -2,11 +2,16 @@ import type { IncomingMessage } from 'node:http';
 import type { RateLimiter } from './rate-limit.js';
 /**
  * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated traffic can drain.
- * Set HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) only when a trusted proxy fronts EVERY request, or clients could mint a fresh bucket per request.
- * HIPPO_TRUSTED_PROXIES (IPs or CIDRs) pins which peers count as that proxy; in a comma-joined chain the key is the rightmost hop no trusted proxy added. */
+ * HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) is read only from a peer in HIPPO_TRUSTED_PROXIES (IPs or CIDRs, or `*` for any peer),
+ * so a caller that reaches the port past the proxy cannot pick its own bucket. In a comma-joined chain the key is the rightmost hop no trusted proxy added. */
 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;
+/** serve() refused HIPPO_CLIENT_IP_HEADER with no HIPPO_TRUSTED_PROXIES: the header would be read from no one, so the setting is a mistake. */
+export declare class UntrustedClientIpHeaderError extends Error {
+    readonly header: string;
+    constructor(header: string);
+}
+/** Checked at boot: a client-IP header needs a trusted-proxy list, and `*` is said once, since it believes any peer. */
+export declare function assertClientIpHeaderPinned(): void;
 /** 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;