hippo-memory 1.70.0 → 1.72.0

package/dist/search/path-context.d.ts

@@ -1,24 +1,11 @@
-/**
- * Extract meaningful path segments from a directory path.
- * Returns tags like ['path:src', 'path:api', 'path:my-project'].
- * Filters out noise (node_modules, .git, Users, home dirs, drive letters).
- */
+/** Extracts meaningful path segments from a directory as tags like ['path:src', 'path:my-project']; filters noise (node_modules, .git, Users, home dirs,
+ * drive letters). */
 export declare function extractPathTags(dirPath: string): string[];
-/**
- * Compute path overlap score between two sets of path tags.
- * Returns 0..1 where 1 = perfect match.
- * Normalizes by the MORE SPECIFIC side (the larger of the two tag sets),
- * so a memory carrying only a bare/generic path tag can no longer score a
- * full 1.0 against a deeply-nested cwd just because its own tiny tag set
- * is fully contained in the query's — genericity is no longer rewarded.
- */
+/** Path overlap score in 0..1 (1 = perfect match), normalized by the MORE SPECIFIC side (the larger tag set),
+ * so a bare/generic path tag cannot score 1.0 against a deeply nested cwd just because its tiny tag set is contained in the query's. */
 export declare function pathOverlapScore(memoryPathTags: string[], currentPathTags: string[]): number;
 /** Weight applied to path overlap score when computing the recall boost multiplier. */
 export declare const PATH_BOOST_WEIGHT = 0.3;
-/**
- * Multiplier applied to a composite recall score for path locality.
- * Filters the memory's tags to path:* itself so call sites cannot drift.
- * Returns 1.0..1.3.
- */
+/** Multiplier (1.0..1.3) applied to a composite recall score for path locality; filters the memory's tags to path:* itself so call sites cannot drift. */
 export declare function pathBoostMultiplier(memoryTags: string[], currentPathTags: string[]): number;
 //# sourceMappingURL=path-context.d.ts.map

package/dist/search/path-context.js

@@ -1,10 +1,7 @@
 // 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'].
- * Filters out noise (node_modules, .git, Users, home dirs, drive letters).
- */
+/** Extracts meaningful path segments from a directory as tags like ['path:src', 'path:my-project']; filters noise (node_modules, .git, Users, home dirs,
+ * drive letters). */
 export function extractPathTags(dirPath) {
     const normalized = dirPath.replace(/\\/g, '/');
     const segments = normalized.split('/').filter(Boolean);
@@ -19,14 +16,8 @@ export function extractPathTags(dirPath) {
         .slice(-PATH_SEGMENTS_KEPT)
         .map(s => `path:${s.toLowerCase()}`);
 }
-/**
- * Compute path overlap score between two sets of path tags.
- * Returns 0..1 where 1 = perfect match.
- * Normalizes by the MORE SPECIFIC side (the larger of the two tag sets),
- * so a memory carrying only a bare/generic path tag can no longer score a
- * full 1.0 against a deeply-nested cwd just because its own tiny tag set
- * is fully contained in the query's — genericity is no longer rewarded.
- */
+/** Path overlap score in 0..1 (1 = perfect match), normalized by the MORE SPECIFIC side (the larger tag set),
+ * so a bare/generic path tag cannot score 1.0 against a deeply nested cwd just because its tiny tag set is contained in the query's. */
 export function pathOverlapScore(memoryPathTags, currentPathTags) {
     if (memoryPathTags.length === 0 || currentPathTags.length === 0)
         return 0;
@@ -38,11 +29,7 @@ export function pathOverlapScore(memoryPathTags, currentPathTags) {
 }
 /** Weight applied to path overlap score when computing the recall boost multiplier. */
 export const PATH_BOOST_WEIGHT = 0.3;
-/**
- * Multiplier applied to a composite recall score for path locality.
- * Filters the memory's tags to path:* itself so call sites cannot drift.
- * Returns 1.0..1.3.
- */
+/** Multiplier (1.0..1.3) applied to a composite recall score for path locality; filters the memory's tags to path:* itself so call sites cannot drift. */
 export function pathBoostMultiplier(memoryTags, currentPathTags) {
     const memPathTags = memoryTags.filter(t => t.startsWith('path:'));
     return 1.0 + pathOverlapScore(memPathTags, currentPathTags) * PATH_BOOST_WEIGHT;

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

@@ -1,7 +1,7 @@
 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 { HippoStore } from '../store/index.js';
+import { type HybridVectorCandidates, type VectorSource } from './vector.js';
 import { type ResultCost, type SearchResult } from '../core/search-types.js';
 export interface PhysicsSearchOptions {
     budget?: number;
@@ -27,6 +27,9 @@ export interface PhysicsSearchOptions {
     /** Where vectors and particles are read; hippo.db under `hippoRoot` when unset. */
     store?: HippoStore;
 }
-/** 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 declare function physicsSearch(query: string, entries: MemoryEntry[], options?: PhysicsSearchOptions): Promise<SearchResult[]>;
+/** physicsSearch on the store the caller names, so a caller holding its request's store never falls back to hippo.db. */
+export declare function physicsSearchIn(source: VectorSource, query: string, entries: MemoryEntry[], options?: PhysicsSearchOptions): Promise<SearchResult[]>;
 //# sourceMappingURL=physics-search.d.ts.map

package/dist/search/physics-search.js

@@ -1,54 +1,62 @@
 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 { evalNow, isRecallBoostAblated, strengthAblation } from '../core/ablation.js';
+import { indexNeedsRebuild } from '../store/embeddings/index.js';
+import { indexedModel } from '../store/vector-index.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 { requireVectorReads, 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);
-    const queryVector = await physicsQueryVector(query, root, store, options.queryEmbedding);
+        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);
+        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);
+        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, 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);
     return fitBudget(merged, options.budget ?? DEFAULT_RECALL_BUDGET, options.minResults ?? 1, options.cost);
 }
 /** The caller's vector, else the provider's; null sends the caller to hybridSearch. */
-async function physicsQueryVector(query, root, store, given) {
+async function physicsQueryVector(query, root, store, deadline, given) {
     if (given && given.length > 0)
         return given;
     // Physics scores against particle positions, not the stored vector index, so a pruned index must not block it.
@@ -58,7 +66,7 @@ async function physicsQueryVector(query, root, store, given) {
             return null;
         if (indexNeedsRebuild(indexedModel(await requireVectorReads(store).embeddingIndexState()), provider.id))
             return null;
-        const [vec] = await provider.embed([query], 'query');
+        const vec = await embedQueryBy(deadline, provider, query);
         return vec && vec.length > 0 ? vec : null;
     }
     catch (err) {
@@ -104,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/rrf.d.ts

@@ -1,43 +1,15 @@
-/**
- * Reciprocal Rank Fusion (Cormack, Clarke, and Buettcher 2009).
- *
- * Fuses N ranked candidate lists into a single ordering by summing
- * weighted 1/(k + rank) contributions per candidate. The constant K is
- * the canonical 60 from the original paper and the value already in use
- * across hippo's `hybridSearch`. Do NOT tune K without an
- * explicit cross-corpus eval — it is calibrated against IR benchmarks
- * and works robustly across BM25/dense/cross-encoder rank-list shapes.
- *
- * Generic over the candidate id type so this helper can be shared by
- * `src/search.ts::hybridSearch` (T = number, idx into MemoryEntry[]) and
- * the LongMemEval hybrid retrieve benchmark (T = string, session_id).
- *
- * Behaviour MUST stay byte-identical to the inline implementation that
- * lived in `src/search.ts:354-374` before extraction (commit ab6c5eb).
- * The `tests/rrf.test.ts` suite is the contract.
- */
+/** Reciprocal Rank Fusion (Cormack, Clarke and Buettcher 2009): fuses N ranked lists by summing weighted 1/(k + rank) per candidate. K is the standard 60,
+ * the value hybridSearch already uses; do NOT tune it without a cross-corpus eval. Generic over the id type (hybridSearch uses number, the LongMemEval
+ * benchmark string). Behaviour MUST stay byte-identical to the inline hybridSearch code it replaced; tests/rrf.test.ts is the contract. */
 export declare const RRF_K = 60;
 export interface RrfFuseOptions {
     /** Smoothing constant. Default RRF_K = 60. */
     k?: number;
-    /**
-     * Rank assigned to candidates absent from a list. Default is
-     * `max(rankedLists.map(l => l.length)) + 1` — the convention used in
-     * the pre-extraction `hybridSearch` code (`entries.length + 1`).
-     */
+    /** Rank assigned to candidates absent from a list; default `max(rankedLists.map(l => l.length)) + 1`, the convention hybridSearch used (`entries.length +
+     * 1`). */
     absentRank?: number;
 }
-/**
- * Fuse N ranked lists into a single Map of candidate id -> RRF score.
- *
- * @param rankedLists  Each inner array is candidates in descending-score order.
- *                     Element at index 0 is rank 1; index 1 is rank 2; etc.
- * @param weights      Per-list weights. weights.length === rankedLists.length.
- *                     Weights are summed without normalisation — pass {0.5, 0.5}
- *                     for symmetric fusion or {0.2, 0.8} for asymmetric.
- * @param options      Optional k override + absentRank override.
- * @returns            Map from candidate id to fused RRF score. Sort descending
- *                     by value to get the fused ordering.
- */
+/** Fuses N ranked lists (each in descending-score order; index 0 is rank 1) into a Map of candidate id -> RRF score; sort by value descending for the fused
+ * order. `weights` has one entry per list and is summed without normalisation; `options` overrides k and absentRank. */
 export declare function rrfFuse<T>(rankedLists: ReadonlyArray<ReadonlyArray<T>>, weights: ReadonlyArray<number>, options?: RrfFuseOptions): Map<T, number>;
 //# sourceMappingURL=rrf.d.ts.map

package/dist/search/rrf.js

@@ -1,34 +1,9 @@
-/**
- * Reciprocal Rank Fusion (Cormack, Clarke, and Buettcher 2009).
- *
- * Fuses N ranked candidate lists into a single ordering by summing
- * weighted 1/(k + rank) contributions per candidate. The constant K is
- * the canonical 60 from the original paper and the value already in use
- * across hippo's `hybridSearch`. Do NOT tune K without an
- * explicit cross-corpus eval — it is calibrated against IR benchmarks
- * and works robustly across BM25/dense/cross-encoder rank-list shapes.
- *
- * Generic over the candidate id type so this helper can be shared by
- * `src/search.ts::hybridSearch` (T = number, idx into MemoryEntry[]) and
- * the LongMemEval hybrid retrieve benchmark (T = string, session_id).
- *
- * Behaviour MUST stay byte-identical to the inline implementation that
- * lived in `src/search.ts:354-374` before extraction (commit ab6c5eb).
- * The `tests/rrf.test.ts` suite is the contract.
- */
+/** Reciprocal Rank Fusion (Cormack, Clarke and Buettcher 2009): fuses N ranked lists by summing weighted 1/(k + rank) per candidate. K is the standard 60,
+ * the value hybridSearch already uses; do NOT tune it without a cross-corpus eval. Generic over the id type (hybridSearch uses number, the LongMemEval
+ * benchmark string). Behaviour MUST stay byte-identical to the inline hybridSearch code it replaced; tests/rrf.test.ts is the contract. */
 export const RRF_K = 60;
-/**
- * Fuse N ranked lists into a single Map of candidate id -> RRF score.
- *
- * @param rankedLists  Each inner array is candidates in descending-score order.
- *                     Element at index 0 is rank 1; index 1 is rank 2; etc.
- * @param weights      Per-list weights. weights.length === rankedLists.length.
- *                     Weights are summed without normalisation — pass {0.5, 0.5}
- *                     for symmetric fusion or {0.2, 0.8} for asymmetric.
- * @param options      Optional k override + absentRank override.
- * @returns            Map from candidate id to fused RRF score. Sort descending
- *                     by value to get the fused ordering.
- */
+/** Fuses N ranked lists (each in descending-score order; index 0 is rank 1) into a Map of candidate id -> RRF score; sort by value descending for the fused
+ * order. `weights` has one entry per list and is summed without normalisation; `options` overrides k and absentRank. */
 export function rrfFuse(rankedLists, weights, options) {
     if (rankedLists.length !== weights.length) {
         throw new Error(`rrfFuse: rankedLists.length (${rankedLists.length}) must match weights.length (${weights.length})`);

package/dist/search/vector.d.ts

@@ -1,5 +1,6 @@
 import type { MemoryEntry } from '../core/memory.js';
 import type { VectorCandidateSpec } from '../store/search-rows.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). */
@@ -14,18 +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 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,34 @@
-import { cosineOf, indexedModel, indexNeedsRebuild } from '../store/embeddings/index.js';
-import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
-import { rethrowIfSqliteBlocked } from '../db/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 '../embeddings/provider.js';
+import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
 import { errorMessage, log } from '../util/log.js';
-import { requireGroup, sqliteStore } from '../store/index.js';
+import { envQueryEmbedTimeoutMs } from '../util/env.js';
+import { requireGroup } from '../store/index.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { currentEntries } from './as-of.js';
+// Jev's default budget (rerankers/jev.ts): each is one off-box call that a recall waits on.
+const QUERY_EMBED_BUDGET_MS = 5_000;
+/** How long one recall waits for its query vector, retries included; HIPPO_QUERY_EMBED_TIMEOUT_MS overrides the default. */
+function queryEmbedBudgetMs() {
+    return envQueryEmbedTimeoutMs() ?? QUERY_EMBED_BUDGET_MS;
+}
+/** One deadline for every query embedding a recall makes, so two stores or a physics fallback share the budget. */
+export function startQueryEmbedDeadline() {
+    return AbortSignal.timeout(queryEmbedBudgetMs());
+}
+/** 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) {
+    try {
+        return (await provider.embed([query], 'query', { signal: deadline }))[0] ?? [];
+    }
+    catch (err) {
+        if (deadline.aborted)
+            return null;
+        throw err;
+    }
+}
 // 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) {
     log.once(`search.bm25-fallback.${reason}`, 'warn', `hybrid search fell back to BM25 only: ${redactSecretsStrict(detail)}`);
@@ -28,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);
@@ -45,11 +69,10 @@ export async function resolveVectorArm(query, entries, options) {
 async function storedVectorsOf(store, reads, ids) {
     return store.vectorViews ? store.vectorViews.storedVectorViews(ids) : reads.storedVectors(ids);
 }
-async function fillVectorArm(arm, query, root, options) {
+async function fillVectorArm(arm, query, { root, store }, options) {
     const provider = resolveEmbeddingProvider(root);
     if (!provider.isAvailable())
         return;
-    const store = options.store ?? sqliteStore(root);
     const reads = requireVectorReads(store);
     const index = await reads.embeddingIndexState();
     if (indexNeedsRebuild(indexedModel(index), provider.id)) {
@@ -61,8 +84,12 @@ async function fillVectorArm(arm, query, root, options) {
     // 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;
-    const [vec] = await provider.embed([query], 'query');
-    arm.queryVector = vec ?? [];
+    const vec = await embedQueryBy(options.queryEmbedDeadline ?? startQueryEmbedDeadline(), provider, query);
+    if (vec === null) {
+        warnBm25Fallback('query-embed-budget', `the ${provider.kind} embedding provider gave no query vector within ${queryEmbedBudgetMs()} ms`);
+        return;
+    }
+    arm.queryVector = vec;
     if (arm.queryVector.length === 0) {
         warnBm25Fallback('empty-query-vector', 'the embedding provider returned no vector for the query');
         return;
@@ -79,8 +106,8 @@ async function fillVectorArm(arm, query, root, options) {
 }
 export function denseScores(arm) {
     const n = arm.entries.length;
-    const cosine = new Array(n).fill(0);
-    const hadVec = new Array(n).fill(false);
+    const cosine = Array(n).fill(0);
+    const hadVec = Array(n).fill(false);
     if (!arm.useEmbeddings)
         return { cosine, hadVec };
     for (let i = 0; i < n; i++) {

package/dist/server/auth.d.ts

@@ -1,23 +1,12 @@
 import type { IncomingMessage } from 'node:http';
 import { type Context } from '../api/index.js';
 import type { ResolvedServeOpts } from './types.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
- * the bare v4 and v6 loopbacks. Anything else is treated as remote.
- */
+/** Recognises loopback remote addresses, including the IPv6-mapped '::ffff:127.0.0.1' Node reports on dual-stack sockets; anything else is remote. */
 export declare function isLoopback(remoteAddress: string | undefined): boolean;
-/**
- * Read the Authorization header in a case-insensitive way and pull the
- * bearer token out. Returns:
- *   - { kind: 'absent' } when no Authorization header is present
- *   - { kind: 'malformed' } when the header is set but not 'Bearer <token>'
- *   - { kind: 'bearer', token } when a non-empty bearer token is present
- *
- * The header NAME is case-insensitive (Node lowercases all header names on
- * IncomingMessage.headers); the SCHEME ('Bearer') is also matched
- * case-insensitively per RFC 6750.
- */
+/** True only for a request made on this machine by its own user: a proxy and a browser page are loopback too, so the socket alone proves nothing. */
+export declare function isLocalCaller(req: IncomingMessage): boolean;
+/** Reads the Authorization header case-insensitively (name and RFC 6750 'Bearer' scheme): { kind: 'absent' }, { kind: 'malformed' } (set but not 'Bearer
+ * <token>'), or { kind: 'bearer', token } for a non-empty token. */
 type AuthHeader = {
     kind: 'absent';
 } | {
@@ -32,19 +21,13 @@ type AuthOpts = Pick<ResolvedServeOpts, 'hippoRoot' | 'authResolver' | 'authReso
 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. */
 export declare const LIMITER_MAX_KEYS = 10000;
-/**
- * Build a per-request Context from the Authorization header and remote
- * address. Throws HttpError(401) for invalid / missing credentials. Reads
- * the store only for an API-key-shaped Bearer token (or any Bearer token when no
- * auth resolver is registered), so loopback no-auth requests stay cheap.
- */
+/** 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>;
-/**
- * Auth check for routes that do not need a tenant Context (e.g. MCP transport,
- * which builds its own root resolution via findHippoRoot). Throws HttpError
- * 401 the same way buildContextWithAuth does, but skips building the Context
- * envelope. Loopback no-auth still passes.
- */
+/** 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>;
 /** 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 declare function heartbeatVerdict(req: IncomingMessage, opts: AuthOpts): Promise<'ok' | 'revoked' | 'unavailable'>;