hippo-memory 1.71.0 → 2.0.0

package/dist/search/physics-search.js

@@ -1,50 +1,55 @@
 import { calculateStrength } from '../core/memory.js';
 import { estimateTokens } from '../util/token-text.js';
-import { evalNow, isRecallBoostAblated } from '../core/ablation.js';
+import { evalNow, isRecallBoostAblated, strengthAblation } from '../core/ablation.js';
 import { indexNeedsRebuild } from '../store/embeddings/index.js';
 import { indexedModel } from '../store/vector-index.js';
-import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
+import { resolveEmbeddingProvider } from '../embeddings/provider.js';
 import { physicsScore as computePhysicsScores, computeMass } from '../core/physics.js';
 import { DEFAULT_PHYSICS_CONFIG } from '../core/physics-config.js';
-import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
 import { compareScoredResults } from '../core/compare.js';
 import { errorMessage, log } from '../util/log.js';
-import { sqliteStore } from '../store/index.js';
 import { churnStaleFactor, summaryMultipliers, summaryScoring } from './boosts.js';
 import { addDagFields, ageInDays } from './breakdown.js';
 import { fitBudget } from './finalize.js';
-import { hybridSearch } from './hybrid.js';
+import { hybridSearch, vectorSourceOf } from './hybrid.js';
 import { currentEntries } from './as-of.js';
-import { embedQueryBy, requireVectorReads, startQueryEmbedDeadline, vectorCandidatesOutside } from './vector.js';
+import { embedQueryBy, requireVectorReads, startQueryEmbedDeadline, vectorCandidatesOutside, } from './vector.js';
 import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
-/** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch. */
+/** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch.
+ *  Reads hippo.db under `hippoRoot` when no store is passed. */
 export async function physicsSearch(query, entries, options = {}) {
+    const source = entries.length > 0 ? vectorSourceOf(options) : undefined;
+    return source ? physicsSearchIn(source, query, entries, options) : [];
+}
+/** physicsSearch on the store the caller names, so a caller holding its request's store never falls back to hippo.db. */
+export async function physicsSearchIn(source, query, entries, options = {}) {
     const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
     const explain = options.explain ?? false;
     const scoring = { now, explain, summary: summaryScoring(options) };
-    if (entries.length === 0 || !options.hippoRoot)
+    if (entries.length === 0)
         return [];
+    const { root, store } = source;
+    const hybrid = { ...options, hippoRoot: root, store };
     // memory_physics keeps only current positions and masses, so a past-dated query must rank without them.
     if (options.asOf)
-        return hybridSearch(query, entries, options);
-    const root = options.hippoRoot;
-    const store = options.store ?? sqliteStore(root);
+        return hybridSearch(query, entries, hybrid);
     // Shared with every hybrid ranking below, so a provider that stalls here is not waited on a second time.
     const queryEmbedDeadline = startQueryEmbedDeadline();
     const queryVector = await physicsQueryVector(query, root, store, queryEmbedDeadline, options.queryEmbedding);
     if (!queryVector)
-        return hybridSearch(query, entries, { ...options, queryEmbedDeadline });
+        return hybridSearch(query, entries, { ...hybrid, queryEmbedDeadline });
     // Checked here too, since a caller's own query vector skips the check inside physicsQueryVector.
     const reads = requireVectorReads(store);
     const pool = currentEntries(await withVectorCandidates(reads, entries, queryVector, options.vectorCandidates), options);
     const physicsMap = await loadCandidateParticles(reads, pool);
     if (!physicsMap)
-        return hybridSearch(query, pool, { ...options, queryEmbedDeadline });
+        return hybridSearch(query, pool, { ...hybrid, queryEmbedDeadline });
     const pools = splitByParticle(pool, physicsMap, queryVector, now);
     const config = options.physicsConfig ?? DEFAULT_PHYSICS_CONFIG;
     const physicsResults = scorePhysicsPool(pools, queryVector, config, scoring);
     const classicResults = pools.classic.length > 0
-        ? await hybridSearch(query, pools.classic, { ...options, queryEmbedDeadline, vectorCandidates: undefined, budget: Infinity, explain })
+        ? await hybridSearch(query, pools.classic, { ...hybrid, queryEmbedDeadline, vectorCandidates: undefined, budget: Infinity, explain })
         : [];
     const merged = mergeScorePools(physicsResults, classicResults);
     merged.sort(compareScoredResults);
@@ -107,7 +112,9 @@ function splitByParticle(pool, physicsMap, queryVector, now) {
         }
         pools.entries.push(entry);
         // EVAL-ONLY ablation (see ablation.ts): persisted masses bake in recall history twice, so the flag recomputes mass live.
-        pools.particles.push(isRecallBoostAblated() ? { ...particle, mass: computeMass(calculateStrength(entry, now), entry.retrieval_count) } : particle);
+        pools.particles.push(isRecallBoostAblated()
+            ? { ...particle, mass: computeMass(calculateStrength(entry, now, { ablation: strengthAblation() }), entry.retrieval_count) }
+            : particle);
     }
     return pools;
 }

package/dist/search/rerank.js

@@ -1,4 +1,4 @@
-import { cosineOf } from '../store/embeddings/index.js';
+import { cosineOf } from '../core/cosine.js';
 const DEFAULT_RERANK_TOP_K = 50;
 // MMR is O(K^2) cosine ops; candidates below this window never survive budget filtering anyway.
 const MMR_CANDIDATE_CAP = 100;

package/dist/search/vector.d.ts

@@ -1,6 +1,6 @@
 import type { MemoryEntry } from '../core/memory.js';
 import type { VectorCandidateSpec } from '../store/search-rows.js';
-import { type EmbeddingProvider } from '../store/embeddings/provider.js';
+import { type EmbeddingProvider } from '../embeddings/provider.js';
 import { type HippoStore, type VectorReads } from '../store/index.js';
 import { type CurrentnessOptions } from './as-of.js';
 /** hybridSearch's vector arm: which rows it may add, plus the caller's JS admission rules (exact private regex, entry filters). */
@@ -15,24 +15,26 @@ export interface VectorArm {
     embeddingIndex: Record<string, ArrayLike<number>>;
     queryVector: number[];
 }
+/** Where the vector arm reads: the embedding provider configured under `root`, and the vectors `store` holds. */
+export interface VectorSource {
+    readonly root: string;
+    readonly store: HippoStore;
+}
 export interface VectorArmOptions extends CurrentnessOptions {
-    hippoRoot?: string;
     vectorCandidates?: HybridVectorCandidates;
-    /** Where vectors are read; hippo.db under `hippoRoot` when unset. */
-    store?: HippoStore;
     /** The deadline a caller already started for this recall's query embedding; a fresh budget when unset. */
     queryEmbedDeadline?: AbortSignal;
 }
 /** One deadline for every query embedding a recall makes, so two stores or a physics fallback share the budget. */
 export declare function startQueryEmbedDeadline(): AbortSignal;
-/** 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 declare function embedQueryBy(deadline: AbortSignal, provider: EmbeddingProvider, query: string): Promise<number[] | null>;
 /** The store's vector reads; a store without them answers 501, as any unported path does. */
 export declare function requireVectorReads(store: HippoStore): VectorReads;
 /** The nearest admitted rows not already in `entries`. */
 export declare function vectorCandidatesOutside(reads: VectorReads, entries: readonly MemoryEntry[], queryVector: readonly number[], spec: HybridVectorCandidates): Promise<MemoryEntry[]>;
 /** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
-export declare function resolveVectorArm(query: string, entries: MemoryEntry[], options: VectorArmOptions): Promise<VectorArm>;
+export declare function resolveVectorArm(query: string, entries: MemoryEntry[], source: VectorSource | undefined, options: VectorArmOptions): Promise<VectorArm>;
 export interface DenseScores {
     cosine: number[];
     /** Whether each entry had a cached doc vector to compare against. */

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 { 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.
@@ -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] ?? [];
     }
@@ -35,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) {
@@ -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,15 +69,14 @@ 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)) {
-        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. */
@@ -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 { envAllowKeylessLocal, envKeylessLocalRole, 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,18 +244,24 @@ 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 };
-    }
-    // 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,
-    };
+    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);
+}
+/** 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 };
+    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. */
@@ -270,6 +277,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.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,9 +1,9 @@
-import { envPort, envRequireAuth, envV1Rps } from '../util/env.js';
-import { existsSync } from 'node:fs';
+import { envAllowCleartext, envCallerRps, envPort, envRequireAuth, envV1Rps } from '../util/env.js';
 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 { 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';
 import { markSharedStore } from '../core/config.js';
 import { auditWriteFailureCount } from '../store/audit.js';
@@ -12,12 +12,10 @@ 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';
-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';
@@ -26,8 +24,9 @@ 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 { assertAddonRoutes, assertPublicJson, dispatchAddonRoute, dispatchPublicJson, dispatchV1Route, isPublicRoute } from './route-table.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
 // listening, a string only for pipe/unix-socket listeners (never used here).
 function isAddressInfo(a) {
@@ -70,13 +69,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 +78,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 });
@@ -184,58 +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 () => { } };
-    }
-    // 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 };
+    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) {
@@ -346,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;
@@ -355,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.
@@ -363,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();
@@ -402,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) {
@@ -421,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,13 +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;
-/** 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;
+/** 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;