hippo-memory 1.69.0 → 1.70.0

package/dist/search/explain.d.ts

@@ -1,4 +1,4 @@
-import type { SearchResult } from './types.js';
+import type { SearchResult } from '../core/search-types.js';
 export interface MatchExplanation {
     /** Human-readable reason string */
     reason: string;

package/dist/search/explain.js

@@ -1,5 +1,6 @@
-import { tokenize } from '../tokenize.js';
+import { tokenize } from '../util/tokenize.js';
 import { matchedQueryTerms } from './bm25.js';
+const COSINE_DECIMALS = 3;
 /** Why a result matched: the overlapping query terms and whether BM25 and/or embedding similarity contributed. */
 export function explainMatch(query, result) {
     const matchedTerms = matchedQueryTerms(new Set(tokenize(query)), result.entry);
@@ -9,7 +10,7 @@ export function explainMatch(query, result) {
     if (hasBm25)
         parts.push(`BM25: matched terms [${matchedTerms.join(', ')}]`);
     if (hasEmbedding)
-        parts.push(`embedding similarity: ${result.cosine.toFixed(3)}`);
+        parts.push(`embedding similarity: ${result.cosine.toFixed(COSINE_DECIMALS)}`);
     if (parts.length === 0)
         parts.push('no direct term or embedding match');
     return {

package/dist/search/finalize.d.ts

@@ -1,5 +1,5 @@
-import type { MemoryEntry } from '../memory.js';
-import type { ResultCost, SearchResult } from './types.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { ResultCost, SearchResult } from '../core/search-types.js';
 /** When an extracted fact and its source both match, keep only the higher-scoring one (usually the fact). */
 export declare function dedupeExtracted(scored: SearchResult[]): SearchResult[];
 /** DAG drill-down: a matched summary pulls its children from `pool` in at 0.9x its score; sorts `results` in place. */

package/dist/search/finalize.js

@@ -1,5 +1,5 @@
-import { estimateTokens } from '../token-ledger.js';
-import { compareScoredResults } from '../compare.js';
+import { estimateTokens } from '../util/token-text.js';
+import { compareScoredResults } from '../core/compare.js';
 import { churnStaleFactor } from './boosts.js';
 /** When an extracted fact and its source both match, keep only the higher-scoring one (usually the fact). */
 export function dedupeExtracted(scored) {
@@ -20,6 +20,7 @@ export function dedupeExtracted(scored) {
     }
     return deduped;
 }
+const DAG_CHILD_SCORE_FACTOR = 0.9;
 /** DAG drill-down: a matched summary pulls its children from `pool` in at 0.9x its score; sorts `results` in place. */
 export function withDagChildren(results, pool) {
     const summaryIds = results.filter((r) => r.entry.tags.includes('dag-summary')).map((r) => r.entry.id);
@@ -30,7 +31,7 @@ export function withDagChildren(results, pool) {
         if (results.some((r) => r.entry.id === child.id))
             continue;
         const parentResult = results.find((r) => r.entry.id === child.dag_parent_id);
-        const childScore = parentResult ? parentResult.score * 0.9 * churnStaleFactor(child) : 0;
+        const childScore = parentResult ? parentResult.score * DAG_CHILD_SCORE_FACTOR * churnStaleFactor(child) : 0;
         results.push({ entry: child, score: childScore, bm25: 0, cosine: 0, tokens: estimateTokens(child.content) });
     }
     results.sort(compareScoredResults);

package/dist/search/fusion.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { DenseScores } from './vector.js';
 /** Opt-in third RRF list ranking in-pool candidates by graph proximity to the strong lexical seeds. */
 export interface GraphStreamOptions {

package/dist/search/fusion.js

@@ -1,6 +1,6 @@
-import { rrfFuse } from '../rrf.js';
-import { graphRankStream, selectGraphSeeds, DEFAULT_GRAPH_SEED_COUNT } from '../graph-stream.js';
-import { compareEntryIdentity } from '../compare.js';
+import { rrfFuse } from './rrf.js';
+import { graphRankStream, selectGraphSeeds, DEFAULT_GRAPH_SEED_COUNT } from '../graph/stream.js';
+import { compareEntryIdentity } from '../core/compare.js';
 // Score desc, then entry identity, so ties cannot leak fresh-ingest order into graph seeds or RRF ranks.
 function rankBy(eligible, scores, entries) {
     return [...eligible].sort((a, b) => {

package/dist/search/hybrid-score.d.ts

@@ -1,7 +1,7 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 import { type BoostContext } from './boosts.js';
 import type { DenseScores } from './vector.js';
-import type { SearchResult } from './types.js';
+import type { SearchResult } from '../core/search-types.js';
 export interface HybridScoreInput {
     entries: MemoryEntry[];
     queryTerms: string[];

package/dist/search/hybrid-score.js

@@ -1,4 +1,4 @@
-import { estimateTokens } from '../token-ledger.js';
+import { estimateTokens } from '../util/token-text.js';
 import { matchedQueryTerms } from './bm25.js';
 import { applyRankBoosts, strengthRecencyMultipliers } from './boosts.js';
 import { addDagFields, ageInDays } from './breakdown.js';

package/dist/search/hybrid.d.ts

@@ -1,10 +1,10 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { RerankerFn, RerankerOptions } from '../rerankers/types.js';
 import { type BM25Corpus } from './bm25.js';
 import { type HybridVectorCandidates } from './vector.js';
 import { type GraphStreamOptions } from './fusion.js';
-import { type ResultCost, type SearchResult } from './types.js';
-import type { HippoStore } from '../store-port.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.js';
+import type { HippoStore } from '../store/index.js';
 export interface HybridSearchOptions {
     budget?: number;
     now?: Date;
@@ -37,7 +37,7 @@ export interface HybridSearchOptions {
     summaryDeboost?: number;
     /** 1.05 micro-boost for summaries rebuilt within 7 days. Default true. */
     summaryFreshness?: boolean;
-    /** Graph-proximity third RRF list; active only with `scoring: 'rrf'`, embeddings and a `hippoRoot`. See src/graph-stream.ts. */
+    /** Graph-proximity third RRF list; active only with `scoring: 'rrf'`, embeddings and a `hippoRoot`. See src/graph/stream.ts. */
     graphStream?: GraphStreamOptions;
     /** Add the rows nearest the query vector, not only rescore `entries`; without it a row no query word matches cannot surface. */
     vectorCandidates?: HybridVectorCandidates;

package/dist/search/hybrid.js

@@ -1,8 +1,8 @@
-import { tokenize } from '../tokenize.js';
-import { evalNow } from '../ablation.js';
-import { extractPathTags } from '../path-context.js';
-import { detectScope } from '../scope.js';
-import { compareScoredResults } from '../compare.js';
+import { tokenize } from '../util/tokenize.js';
+import { evalNow } from '../core/ablation.js';
+import { extractPathTags } from './path-context.js';
+import { detectScope } from '../sharing/scope.js';
+import { compareScoredResults } from '../core/compare.js';
 import { bm25Score, buildCorpus, entryText } from './bm25.js';
 import { currentEntries } from './as-of.js';
 import { summaryScoring } from './boosts.js';
@@ -12,11 +12,14 @@ import { fuseRanks } from './fusion.js';
 import { scoreHybridPool } from './hybrid-score.js';
 import { applyMmrWindow, applyReranker } from './rerank.js';
 import { dedupeExtracted, fitBudget, withDagChildren } from './finalize.js';
-import { DEFAULT_RECALL_BUDGET } from './types.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
+// Share of the blended score that cosine takes, and the relevance side of the MMR relevance-versus-diversity trade.
+const DEFAULT_EMBEDDING_WEIGHT = 0.6;
+const DEFAULT_MMR_LAMBDA = 0.7;
 /** BM25 blended with cosine similarity when stored vectors and a provider are available, BM25 * strength * recency otherwise. */
 export async function hybridSearch(query, entries, options = {}) {
     const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
-    const embeddingWeight = options.embeddingWeight ?? 0.6;
+    const embeddingWeight = options.embeddingWeight ?? DEFAULT_EMBEDDING_WEIGHT;
     const pool = currentEntries(entries, options);
     if (pool.length === 0)
         return [];
@@ -57,7 +60,7 @@ function hybridBoostContext(query, pool, now, options) {
 }
 /** MMR when vectors are loaded, then the optional reranker. */
 async function orderHybrid(query, scored, arm, options) {
-    const mmrLambda = options.mmrLambda ?? 0.7;
+    const mmrLambda = options.mmrLambda ?? DEFAULT_MMR_LAMBDA;
     const applyMmr = (options.mmr ?? true) && arm.useEmbeddings && scored.length > 1 && mmrLambda < 1;
     const ordered = applyMmr ? applyMmrWindow(scored, arm.embeddingIndex, mmrLambda, options.explain ?? false) : scored;
     return options.reranker ? applyReranker(query, ordered, options.reranker, options.rerankerOptions) : ordered;

package/dist/{multihop.d.ts → search/multihop.d.ts}

@@ -1,5 +1,5 @@
-import type { MemoryEntry } from './memory.js';
-import { type ResultCost, type SearchResult } from './search/types.js';
+import type { MemoryEntry } from '../core/memory.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.js';
 export declare function multihopSearch(query: string, entries: MemoryEntry[], options?: {
     budget?: number;
     now?: Date;

package/dist/{multihop.js → search/multihop.js}

@@ -1,12 +1,14 @@
-import { fitBudget } from './search/finalize.js';
-import { search } from './search/bm25-search.js';
-import { DEFAULT_RECALL_BUDGET } from './search/types.js';
+import { compareScoresDesc } from '../core/compare.js';
+import { fitBudget } from './finalize.js';
+import { search } from './bm25-search.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
+const PASS1_TOP_K = 10;
 export function multihopSearch(query, entries, options = {}) {
     const budget = options.budget ?? DEFAULT_RECALL_BUDGET;
     // Pass 1 searches wide to find entities, so each return fits the caller's budget, as search() does.
     const fit = (ordered) => fitBudget(ordered, budget, options.minResults ?? 1, options.cost);
     const pass1 = search(query, entries, { ...options, budget: budget * 2 });
-    const topK = pass1.slice(0, 10);
+    const topK = pass1.slice(0, PASS1_TOP_K);
     if (topK.length === 0)
         return [];
     const entityTags = new Set();
@@ -35,6 +37,6 @@ export function multihopSearch(query, entries, options = {}) {
     // PLAIN stable score sort on purpose -- pass1/pass2 inputs are
     // deterministically ordered (search() carries the content tail), stability
     // inherits that, and ties keep pass-1 results ahead of pass-2 follow-ups.
-    return fit([...merged.values()].sort((a, b) => b.score - a.score));
+    return fit([...merged.values()].sort((a, b) => compareScoresDesc(a.score, b.score)));
 }
 //# sourceMappingURL=multihop.js.map

package/dist/{path-context.js → search/path-context.js}

@@ -1,3 +1,5 @@
+// Keeps the last meaningful segments, the most specific ones.
+const PATH_SEGMENTS_KEPT = 4;
 /**
  * Extract meaningful path segments from a directory path.
  * Returns tags like ['path:src', 'path:api', 'path:my-project'].
@@ -14,7 +16,7 @@ export function extractPathTags(dirPath) {
     ]);
     return segments
         .filter(s => s.length >= 2 && !noise.has(s.toLowerCase()))
-        .slice(-4) // keep last 4 meaningful segments (most specific)
+        .slice(-PATH_SEGMENTS_KEPT)
         .map(s => `path:${s.toLowerCase()}`);
 }
 /**

package/dist/search/physics-search.d.ts

@@ -1,8 +1,8 @@
-import { type MemoryEntry } from '../memory.js';
-import { type PhysicsConfig } from '../physics-config.js';
-import { type HippoStore } from '../store-port.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type PhysicsConfig } from '../core/physics-config.js';
+import { type HippoStore } from '../store/index.js';
 import { type HybridVectorCandidates } from './vector.js';
-import { type ResultCost, type SearchResult } from './types.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.js';
 export interface PhysicsSearchOptions {
     budget?: number;
     now?: Date;

package/dist/search/physics-search.js

@@ -1,21 +1,21 @@
-import { calculateStrength } from '../memory.js';
-import { estimateTokens } from '../token-ledger.js';
-import { evalNow, isRecallBoostAblated } from '../ablation.js';
-import { indexedModel, indexNeedsRebuild } from '../embeddings.js';
-import { resolveEmbeddingProvider } from '../embedding-provider.js';
-import { physicsScore as computePhysicsScores, computeMass } from '../physics.js';
-import { DEFAULT_PHYSICS_CONFIG } from '../physics-config.js';
-import { rethrowIfSqliteBlocked } from '../db.js';
-import { compareScoredResults } from '../compare.js';
-import { log } from '../log.js';
-import { sqliteStore } from '../store-port.js';
+import { calculateStrength } from '../core/memory.js';
+import { estimateTokens } from '../util/token-text.js';
+import { evalNow, isRecallBoostAblated } from '../core/ablation.js';
+import { indexedModel, indexNeedsRebuild } from '../store/embeddings/index.js';
+import { resolveEmbeddingProvider } from '../store/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 { 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 { currentEntries } from './as-of.js';
 import { requireVectorReads, vectorCandidatesOutside } from './vector.js';
-import { DEFAULT_RECALL_BUDGET } from './types.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. */
 export async function physicsSearch(query, entries, options = {}) {
     const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
@@ -63,7 +63,7 @@ async function physicsQueryVector(query, root, store, given) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.debug(`physics search: query embed failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`physics search: query embed failed, using hybrid: ${errorMessage(err)}`);
         return null;
     }
 }
@@ -75,7 +75,7 @@ async function withVectorCandidates(reads, entries, queryVector, spec) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.warn(`physics search ranked the lexical pool only; the vector lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        log.warn(`physics search ranked the lexical pool only; the vector lookup failed: ${errorMessage(err)}`);
         return entries;
     }
 }
@@ -86,7 +86,7 @@ async function loadCandidateParticles(reads, pool) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.debug(`physics search: state load failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`physics search: state load failed, using hybrid: ${errorMessage(err)}`);
         return null;
     }
 }

package/dist/search/rerank.d.ts

@@ -1,10 +1,10 @@
 import type { RerankerFn, RerankerOptions } from '../rerankers/types.js';
-import type { SearchResult } from './types.js';
+import type { SearchResult } from '../core/search-types.js';
 /** MMR: repeatedly picks the candidate maximising lambda * relevance - (1 - lambda) * max(cos(cand, picked)).
  *  Input must be sorted by relevance; strict `>` keeps ties first-wins, so a deterministic input stays deterministic. */
-export declare function mmrRerank(scored: SearchResult[], embeddingIndex: Record<string, number[]>, lambda: number, explain: boolean): SearchResult[];
+export declare function mmrRerank(scored: SearchResult[], embeddingIndex: Record<string, ArrayLike<number>>, lambda: number, explain: boolean): SearchResult[];
 /** MMR over the top window only; the tail keeps its relevance order. */
-export declare function applyMmrWindow(scored: SearchResult[], embeddingIndex: Record<string, number[]>, lambda: number, explain: boolean): SearchResult[];
+export declare function applyMmrWindow(scored: SearchResult[], embeddingIndex: Record<string, ArrayLike<number>>, lambda: number, explain: boolean): SearchResult[];
 /** Runs the reranker over the top `topK` (default 50) and stamps pre and post ranks; see src/rerankers/types.ts. */
 export declare function applyReranker(query: string, ordered: SearchResult[], reranker: RerankerFn, rerankerOptions?: RerankerOptions): Promise<SearchResult[]>;
 //# sourceMappingURL=rerank.d.ts.map

package/dist/search/rerank.js

@@ -1,4 +1,5 @@
-import { cosineSimilarity } from '../embeddings.js';
+import { cosineOf } from '../store/embeddings/index.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;
 /** MMR: repeatedly picks the candidate maximising lambda * relevance - (1 - lambda) * max(cos(cand, picked)).
@@ -39,7 +40,7 @@ function maxSimilarityToPicked(vi, picked, embeddingIndex) {
         const vp = embeddingIndex[p.entry.id];
         if (!vp || vp.length !== vi.length)
             continue;
-        const sim = Math.max(0, cosineSimilarity(vi, vp));
+        const sim = Math.max(0, cosineOf(vi, vp));
         if (sim > maxSim)
             maxSim = sim;
     }
@@ -63,7 +64,7 @@ export function applyMmrWindow(scored, embeddingIndex, lambda, explain) {
 }
 /** Runs the reranker over the top `topK` (default 50) and stamps pre and post ranks; see src/rerankers/types.ts. */
 export async function applyReranker(query, ordered, reranker, rerankerOptions) {
-    const topK = rerankerOptions?.topK ?? 50;
+    const topK = rerankerOptions?.topK ?? DEFAULT_RERANK_TOP_K;
     const head = ordered.slice(0, topK).map((r, i) => ({ ...r, preRerankRank: i + 1 }));
     const tail = ordered.slice(topK);
     const reranked = await reranker(query, head, { ...rerankerOptions, topK });

package/dist/search/temporal.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 export type TemporalDirection = 'recent' | 'oldest' | null;
 export declare function detectTemporalDirection(query: string): TemporalDirection;
 export interface TemporalRange {

package/dist/search/temporal.js

@@ -22,6 +22,9 @@ export function computeTemporalRange(entries) {
     }
     return { minTime, maxTime };
 }
+// A temporal cue scales rank linearly across the pool time range, from the floor to floor + span.
+const TEMPORAL_BOOST_FLOOR = 0.8;
+const TEMPORAL_BOOST_SPAN = 0.4;
 export function temporalBoost(entry, direction, range) {
     if (!direction)
         return 1.0;
@@ -31,10 +34,10 @@ export function temporalBoost(entry, direction, range) {
     const entryTime = new Date(entry.created).getTime();
     const normalized = (entryTime - range.minTime) / span;
     if (direction === 'recent') {
-        return 0.8 + 0.4 * normalized;
+        return TEMPORAL_BOOST_FLOOR + TEMPORAL_BOOST_SPAN * normalized;
     }
     else {
-        return 0.8 + 0.4 * (1 - normalized);
+        return TEMPORAL_BOOST_FLOOR + TEMPORAL_BOOST_SPAN * (1 - normalized);
     }
 }
 /** The query's temporal cue and, only when there is one, the pool's time range. */

package/dist/search/vector.d.ts

@@ -1,6 +1,6 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { VectorCandidateSpec } from '../store/search-rows.js';
-import { type HippoStore, type VectorReads } from '../store-port.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). */
 export type HybridVectorCandidates = VectorCandidateSpec & {
@@ -11,7 +11,7 @@ export interface VectorArm {
     entries: MemoryEntry[];
     addedRows: boolean;
     useEmbeddings: boolean;
-    embeddingIndex: Record<string, number[]>;
+    embeddingIndex: Record<string, ArrayLike<number>>;
     queryVector: number[];
 }
 export interface VectorArmOptions extends CurrentnessOptions {

package/dist/search/vector.js

@@ -1,9 +1,9 @@
-import { cosineSimilarity, indexedModel, indexNeedsRebuild } from '../embeddings.js';
-import { resolveEmbeddingProvider } from '../embedding-provider.js';
-import { rethrowIfSqliteBlocked } from '../db.js';
-import { log } from '../log.js';
-import { requireGroup, sqliteStore } from '../store-port.js';
-import { redactSecretsStrict } from '../secret-detect.js';
+import { cosineOf, indexedModel, indexNeedsRebuild } from '../store/embeddings/index.js';
+import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
+import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { errorMessage, log } from '../util/log.js';
+import { requireGroup, sqliteStore } from '../store/index.js';
+import { redactSecretsStrict } from '../util/secret-detect.js';
 import { currentEntries } from './as-of.js';
 // Search runs on every hook prompt, so one line per reason per process says why vectors went unused without flooding stderr.
 function warnBm25Fallback(reason, detail) {
@@ -23,7 +23,9 @@ export function requireVectorReads(store) {
 /** The nearest admitted rows not already in `entries`. */
 export async function vectorCandidatesOutside(reads, entries, queryVector, spec) {
     const inPool = new Set(entries.map((e) => e.id));
-    return (await reads.nearestEntries(queryVector, spec)).filter((e) => !inPool.has(e.id) && (spec.admit?.(e) ?? true));
+    // The port takes data alone: `admit` is this side's rule, and a function cannot be sent to a store on another thread.
+    const { admit, ...stored } = 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) {
@@ -35,10 +37,14 @@ export async function resolveVectorArm(query, entries, options) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        warnBm25Fallback('error', err instanceof Error ? err.message : String(err));
+        warnBm25Fallback('error', errorMessage(err));
     }
     return arm;
 }
+// Views when the store has them, so a search copies no vector; the number[] copies score the same.
+async function storedVectorsOf(store, reads, ids) {
+    return store.vectorViews ? store.vectorViews.storedVectorViews(ids) : reads.storedVectors(ids);
+}
 async function fillVectorArm(arm, query, root, options) {
     const provider = resolveEmbeddingProvider(root);
     if (!provider.isAvailable())
@@ -51,7 +57,7 @@ async function fillVectorArm(arm, query, root, options) {
         return;
     }
     const spec = options.vectorCandidates;
-    const vectors = await reads.storedVectors(arm.entries.map((e) => e.id));
+    const vectors = await storedVectorsOf(store, reads, arm.entries.map((e) => e.id));
     // Only spend a (possibly paid, off-box) query embedding when there is a stored vector this search can use.
     if (vectors.size === 0 && !(spec !== undefined && index.hasVectors))
         return;
@@ -65,7 +71,7 @@ async function fillVectorArm(arm, query, root, options) {
     if (added.length > 0) {
         arm.addedRows = true;
         arm.entries = currentEntries([...arm.entries, ...added], options);
-        for (const [id, v] of await reads.storedVectors(added.map((e) => e.id)))
+        for (const [id, v] of await storedVectorsOf(store, reads, added.map((e) => e.id)))
             vectors.set(id, v);
     }
     arm.embeddingIndex = Object.fromEntries(vectors);
@@ -80,7 +86,7 @@ export function denseScores(arm) {
     for (let i = 0; i < n; i++) {
         const cached = arm.embeddingIndex[arm.entries[i].id];
         hadVec[i] = Boolean(cached && arm.queryVector.length > 0);
-        cosine[i] = hadVec[i] ? Math.max(0, cosineSimilarity(arm.queryVector, cached)) : 0;
+        cosine[i] = hadVec[i] ? Math.max(0, cosineOf(arm.queryVector, cached)) : 0;
     }
     return { cosine, hadVec };
 }

package/dist/server/auth.d.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage } from 'node:http';
-import { type Context } from '../api.js';
+import { type Context } from '../api/index.js';
 import type { ResolvedServeOpts } from './types.js';
 /**
  * Recognise loopback remote addresses. Node reports IPv6-mapped IPv4 as

package/dist/server/auth.js

@@ -1,13 +1,13 @@
 // Bearer and loopback auth for the HTTP server.
-import { envRequireAuth } from '../env.js';
-import { resolveTenantId } from '../tenant.js';
-import { log } from '../log.js';
-import { API_KEY_PREFIX, verifyApiKeyCached } from '../auth.js';
-import { ownerOrSubject } from '../api.js';
-import { HttpError, isCrossSite, isHeaderString, LOOPBACK_HOST_HEADER, MAX_ID_LEN } from '../http-util.js';
-import { clientIpForRateLimit, subscriberKey } from './client-ip.js';
-import { requestIds } from './request.js';
-import { isJsonString } from '../json.js';
+import { envRequireAuth } from '../util/env.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { 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 { clientLimitKey } from './client-ip.js';
+import { keyCheckBounds } from './key-check-bounds.js';
+import { isJsonString } from '../util/json.js';
 /**
  * Recognise loopback remote addresses. Node reports IPv6-mapped IPv4 as
  * '::ffff:127.0.0.1' on dual-stack sockets, so we accept that alongside
@@ -27,6 +27,7 @@ export function isLoopback(remoteAddress) {
 // A proxy on this host (nginx, Caddy, cloudflared) connects from loopback, so these headers mean the caller is not local.
 const PROXY_HEADERS = [
     'forwarded', 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'cf-connecting-ip', 'true-client-ip',
+    'fly-client-ip',
 ];
 // A browser on this machine is loopback too, so the no-key fallback also needs a local Host and a same-site caller.
 function assertLocalCaller(req) {
@@ -35,7 +36,7 @@ function assertLocalCaller(req) {
     const proxyHeader = PROXY_HEADERS.find((name) => req.headers[name] !== undefined);
     if (proxyHeader !== undefined) {
         log.warn(`proxied loopback request refused: it carries ${proxyHeader}, so the no-key local fallback does not apply. ` +
-            'Send an API key (hippo auth create, then Authorization: Bearer hk_...).', { requestId: requestIds.get(req) });
+            'Send an API key (hippo auth create, then Authorization: Bearer hk_...).');
         throw new HttpError(401, 'auth required');
     }
     const host = req.headers.host;
@@ -140,7 +141,7 @@ const DEFAULT_RESOLVER_DEADLINE_MS = 5000;
 function chargeScryptRun(req, opts) {
     const limiter = opts.failedAuthLimiter;
     // Reserving rather than peeking bounds scrypt runs exactly, even when concurrent misses await a slow store.
-    if (limiter && !limiter.check(subscriberKey(clientIpForRateLimit(req)))) {
+    if (limiter && !limiter.check(clientLimitKey(req))) {
         throw new HttpError(429, 'too many key checks from this address', limiter.retryAfterSec);
     }
 }
@@ -153,7 +154,12 @@ async function resolveBearer(req, token, opts) {
         const clean = await askResolver(opts.authResolver, token, deadlineMs);
         return { ...clean, viaAuthResolver: true, owner: clean.subject }; // a resolver vouches for a person, never names one
     }
-    const key = await verifyApiKeyCached(opts.hippoRoot, token, opts.store, () => chargeScryptRun(req, opts));
+    const key = await verifyApiKeyCached(token, opts.store, (keyId, derive) => {
+        // The key's own bucket first, so a flood on one key id ends at its five tries and leaves the address's budget to the callers who share it.
+        keyChecks.admit(keyId, clientLimitKey(req));
+        chargeScryptRun(req, opts);
+        return keyChecks.run(derive);
+    });
     if (!key)
         throw new HttpError(401, 'invalid api key');
     const id = { tenantId: key.tenantId, subject: `api_key:${key.keyId}`, role: key.role, scopes: key.scopes };
@@ -189,9 +195,11 @@ function bearerActor(id) {
 }
 /** Key cap for every serve() bucket, shared by the warn map so it never tracks more callers than the buckets do. */
 export const LIMITER_MAX_KEYS = 10_000;
+// One for the process, as the thread pool its derivations run on is.
+const keyChecks = keyCheckBounds(LIMITER_MAX_KEYS);
 const CALLER_WARN_EVERY_MS = 60_000;
 const callerWarnedAt = new Map();
-function warnCallerLimited(req, key, tenantId, person) {
+function warnCallerLimited(key, tenantId, person) {
     const now = Date.now();
     const last = callerWarnedAt.get(key);
     if (last !== undefined && now - last < CALLER_WARN_EVERY_MS)
@@ -203,9 +211,9 @@ function warnCallerLimited(req, key, tenantId, person) {
             callerWarnedAt.delete(oldest.value);
     }
     callerWarnedAt.set(key, now);
-    log.warn('caller over its rate limit; its further 429s this minute are not logged', { tenant: tenantId, person, requestId: requestIds.get(req) });
+    log.warn('caller over its rate limit; its further 429s this minute are not logged', { tenant: tenantId, person });
 }
-function chargeCaller(req, tenantId, actor, opts) {
+function chargeCaller(tenantId, actor, opts) {
     const limiter = opts.callerLimiter;
     if (!limiter)
         return;
@@ -213,7 +221,7 @@ function chargeCaller(req, tenantId, actor, opts) {
     const key = `${tenantId}\u0000${person}`;
     if (limiter.check(key))
         return;
-    warnCallerLimited(req, key, tenantId, person);
+    warnCallerLimited(key, tenantId, person);
     throw new HttpError(429, 'rate limit exceeded for this caller', limiter.retryAfterSec);
 }
 /**
@@ -226,7 +234,7 @@ export async function buildContextWithAuth(req, opts) {
     const id = await checkAuth(req, opts);
     if (id !== null) {
         const actor = bearerActor(id);
-        chargeCaller(req, id.tenantId, actor, opts);
+        chargeCaller(id.tenantId, actor, opts);
         return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor, store: opts.store };
     }
     // Loopback fallback is process-local, treat as admin.
@@ -246,7 +254,7 @@ export async function buildContextWithAuth(req, opts) {
 export async function requireAuth(req, opts) {
     const id = await checkAuth(req, opts);
     if (id !== null)
-        chargeCaller(req, id.tenantId, bearerActor(id), opts);
+        chargeCaller(id.tenantId, bearerActor(id), opts);
 }
 /** Never rejects or charges a caller bucket: an outage (5xx) or a throttle (429) skips one tick; only a definite 4xx denial closes the stream. */
 export async function heartbeatVerdict(req, opts) {

package/dist/server/boot.d.ts

@@ -0,0 +1,24 @@
+import type { ServeOpts, ServerHandle } from './types.js';
+/**
+ * Boot the HTTP daemon on host:port and write the pidfile under hippoRoot.
+ *
+ * Refuses non-loopback hosts at boot unless
+ * HIPPO_REQUIRE_AUTH=1 is set. The auth middleware (buildContextWithAuth /
+ * requireAuth) has shipped and every route checks it except GET /health
+ * (public by design for platform health checks) and the two connector
+ * webhooks in PUBLIC_ROUTES, which are HMAC-gated by their own signing
+ * secrets and 404 when those secrets are unset, and any publicJson GET path. But the loopback
+ * no-auth fallback inside buildContextWithAuth still admits unauthenticated
+ * requests from a loopback remote address (unless they carry Forwarded,
+ * X-Forwarded-For/-Host/-Proto, X-Real-IP, Cf-Connecting-Ip, True-Client-Ip or Fly-Client-Ip, which mark a same-host proxy and get
+ * a 401 like any keyless remote request), so binding to a non-loopback host
+ * is only safe once that fallback is disabled with HIPPO_REQUIRE_AUTH=1,
+ * which forces every request (loopback or not) through Bearer-token
+ * validation. Without that env var set, a non-loopback bind would expose the
+ * DB to the network with no auth, so we fail fast instead.
+ *
+ * Use port: 0 in tests to bind to an ephemeral port and read the actual
+ * port back via server.address() after listen.
+ */
+export declare function serve(opts: ServeOpts): Promise<ServerHandle>;
+//# sourceMappingURL=boot.d.ts.map