hippo-memory 1.69.0 → 1.71.0

package/dist/{local-embedding.js → store/embeddings/local.js}

@@ -1,10 +1,10 @@
-// The local Transformers.js embedder, a leaf so embedding-provider.ts can wrap it without importing embeddings.ts.
-import { envModelCache } from './env.js';
+// The local Transformers.js embedder, a leaf so provider.ts can wrap it without importing index.ts.
+import { envModelCache } from '../../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { createRequire } from 'module';
-import { loadConfig } from './config.js';
-import { log } from './log.js';
+import { loadConfig } from '../../core/config.js';
+import { errorMessage, log } from '../../util/log.js';
 const _require = createRequire(import.meta.url);
 let _embeddingAvailable = null;
 // A pipeline is expensive to load, so one instance per model is kept for the process.
@@ -25,11 +25,6 @@ export function prefixFor(model, role) {
     }
     return '';
 }
-// Use Function constructor to bypass TypeScript static module resolution
-// for optional peer dependencies that may not be installed.
-// SAFETY: `import(s)` always resolves to a module namespace object (or rejects);
-// Promise<object> names that honestly without claiming a specific module shape.
-const _dynImport = new Function('s', 'return import(s)');
 /** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
 export function isEmbeddingAvailable() {
     if (_embeddingAvailable !== null)
@@ -71,68 +66,73 @@ function resolveTransformersPackage() {
         return null; // neither optional package is installed; callers fall back to no local embeddings
     }
 }
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 async function loadPipeline(model) {
-    if (_pipelineInstances.has(model))
-        return _pipelineInstances.get(model);
-    if (_pipelineLoading.has(model))
-        return _pipelineLoading.get(model);
-    const loading = (async () => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const pkg = resolveTransformersPackage();
-        if (!pkg) {
-            _pipelineErrors.set(model, 'no transformers package is installed');
-            return null;
-        }
-        let pipelineFn = null;
-        try {
-            // SAFETY: the resolved module's shape is untyped by design (optional peer
-            // dependency); pipelineFn/mod.env are read defensively below and any
-            // failure to find a usable pipeline falls through to `return null`.
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const mod = await _dynImport(pkg);
-            if (envModelCache()) {
-                if (mod.env) {
-                    mod.env.cacheDir = envModelCache();
-                    mod.env.localModelPath = envModelCache();
-                    mod.env.allowRemoteModels = false;
-                }
-            }
-            pipelineFn = mod.pipeline ?? mod.default?.pipeline;
-        }
-        catch (err) {
-            // String(err) keeps a Node error's [ERR_...] code, which callers match on.
-            const reason = `transformers import failed (${pkg}): ${String(err)}`;
-            log.debug(reason);
-            _pipelineErrors.set(model, reason);
-            return null;
-        }
-        if (!pipelineFn) {
-            _pipelineErrors.set(model, `${pkg} exports no pipeline function`);
-            return null;
-        }
-        // The offline bundle used in egress-blocked sandboxes ships only the FP32 model, so use whichever file is on disk.
-        const cacheRoot = envModelCache();
-        const quantized = !cacheRoot
-            || fs.existsSync(path.join(cacheRoot, model, 'onnx', 'model_quantized.onnx'));
-        try {
-            const instance = await pipelineFn('feature-extraction', model, { quantized });
-            _pipelineInstances.set(model, instance);
-            return instance;
-        }
-        catch (err) {
-            const reason = `embedding pipeline load failed (${model}): ${String(err)}`;
-            log.debug(reason);
-            _pipelineErrors.set(model, reason);
-            return null;
-        }
-        finally {
-            _pipelineLoading.delete(model);
-        }
-    })();
+    const loaded = _pipelineInstances.get(model);
+    if (loaded)
+        return loaded;
+    const inFlight = _pipelineLoading.get(model);
+    if (inFlight)
+        return inFlight;
+    const loading = createPipeline(model);
     _pipelineLoading.set(model, loading);
     return loading;
 }
+/** The model's pipeline, or null with the reason recorded in `_pipelineErrors`. */
+async function createPipeline(model) {
+    const pkg = resolveTransformersPackage();
+    if (!pkg) {
+        _pipelineErrors.set(model, 'no transformers package is installed');
+        return null;
+    }
+    const pipelineFn = await importPipelineFactory(pkg, model);
+    if (!pipelineFn)
+        return null;
+    // The offline bundle used in egress-blocked sandboxes ships only the FP32 model, so use whichever file is on disk.
+    const cacheRoot = envModelCache();
+    const quantized = !cacheRoot
+        || fs.existsSync(path.join(cacheRoot, model, 'onnx', 'model_quantized.onnx'));
+    try {
+        const instance = await pipelineFn('feature-extraction', model, { quantized });
+        _pipelineInstances.set(model, instance);
+        return instance;
+    }
+    catch (err) {
+        const reason = `embedding pipeline load failed (${model}): ${String(err)}`;
+        log.debug(reason);
+        _pipelineErrors.set(model, reason);
+        return null;
+    }
+    finally {
+        _pipelineLoading.delete(model);
+    }
+}
+/** The package's `pipeline` function, or null with the reason recorded in `_pipelineErrors`. */
+async function importPipelineFactory(pkg, model) {
+    let pipelineFn = null;
+    try {
+        // The package is an optional peer, so the dynamic import is typed by what this file reads; a missing export falls to the null below.
+        const mod = await import(/* @vite-ignore */ pkg);
+        const cache = envModelCache();
+        if (cache && mod.env) {
+            mod.env.cacheDir = cache;
+            mod.env.localModelPath = cache;
+            mod.env.allowRemoteModels = false;
+        }
+        pipelineFn = mod.pipeline ?? mod.default?.pipeline ?? null;
+    }
+    catch (err) {
+        // String(err) keeps a Node error's [ERR_...] code, which callers match on.
+        const reason = `transformers import failed (${pkg}): ${String(err)}`;
+        log.debug(reason);
+        _pipelineErrors.set(model, reason);
+        return null;
+    }
+    if (!pipelineFn) {
+        _pipelineErrors.set(model, `${pkg} exports no pipeline function`);
+        return null;
+    }
+    return pipelineFn;
+}
 /** Throws, with the reason, when the model's pipeline cannot load: a provider-level failure, not a per-item skip. */
 export async function requireLocalPipeline(model) {
     if (await loadPipeline(model))
@@ -163,19 +163,13 @@ export async function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role)
             return [];
         const prefix = prefixFor(model, role);
         const input = prefix ? `${prefix}${text}` : text;
-        // SAFETY: pipe() is a Transformers.js feature-extraction pipeline call;
-        // its untyped output is read defensively below (only `.data`, cast on
-        // the return line to the documented Float32Array tensor shape).
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const output = await pipe(input, { pooling: poolingFor(model), normalize: true });
-        // SAFETY: output.data is a Float32Array per the feature-extraction
-        // pipeline's documented tensor output shape.
         return Array.from(output.data);
     }
     catch (err) {
         // The caller sees `[]` and names the memory; the reason only shows at debug.
-        log.debug(`local embedding failed: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`local embedding failed: ${errorMessage(err)}`);
         return [];
     }
 }
-//# sourceMappingURL=local-embedding.js.map
+//# sourceMappingURL=local.js.map

package/dist/store/embeddings/provider.d.ts

@@ -0,0 +1,40 @@
+/** Pluggable embedding providers; local `@huggingface/transformers` is the zero-dependency default, OpenAI / Voyage / Cohere are opt-in via native `fetch`.
+ * Local `id` is the bare model string, API `id` is `${kind}:${model}`; the stored identity adds `#t<N>` (`embeddingIndexIdentity`), so changes reindex.
+ * `embed()` MAY throw on hard transport/auth failure so a reindex aborts atomically; hot paths wrap it and fall back to BM25. */
+import { type EmbeddingRole } from './local.js';
+export type EmbeddingProviderKind = 'local' | 'openai' | 'voyage' | 'cohere';
+export declare const API_PROVIDER_KINDS: readonly EmbeddingProviderKind[];
+export interface EmbedCallOptions {
+    /** Ends the whole call when it aborts, every batch and retry included. The local provider runs in process and ignores it. */
+    signal?: AbortSignal;
+}
+export interface EmbeddingProvider {
+    readonly kind: EmbeddingProviderKind;
+    readonly model: string;
+    /** Identity recorded in DB meta to drive reindex-on-change: bare model string for local, `${kind}:${model}` for api. */
+    readonly id: string;
+    /** Known fixed output dimension, if any (undefined for local / unknown). */
+    readonly dimensions?: number;
+    /** Env var holding this provider's API key (undefined for the local provider). */
+    readonly keyEnv?: string;
+    /** local -> dependency installed; api -> key present. NEVER throws. */
+    isAvailable(): boolean;
+    /** Batch-embed: one row per input in order, `[]` when that item could not be embedded.
+     * MAY throw on a hard transport/auth failure so a reindex aborts before saving a partial index. */
+    embed(texts: string[], role?: EmbeddingRole, call?: EmbedCallOptions): Promise<number[][]>;
+}
+export interface ResolveProviderOptions {
+    /** Explicit model override (mirrors resolveEmbeddingModel's explicitModel). */
+    model?: string;
+    /** Explicit provider override (mainly for tests). */
+    provider?: EmbeddingProviderKind;
+}
+/** Build the active embedding provider from config (or an explicit override). A missing key never throws here (it surfaces via `isAvailable()`);
+ * only an invalid config (e.g. insecure apiBaseUrl) throws, deliberately loud, so hot-path callers wrap it. */
+export declare function resolveEmbeddingProvider(hippoRoot: string, opts?: ResolveProviderOptions): EmbeddingProvider;
+/** The reindex identity for the active provider; use it, NOT resolveEmbeddingModel, wherever `embeddingModelRequiresReindex` / stored-model comparisons
+ * happen. */
+export declare function resolveEmbeddingIdentity(hippoRoot: string, opts?: ResolveProviderOptions): string;
+/** Provider-aware availability for a store (local: dependency installed; api: key present); use where the decision to embed is made. */
+export declare function isEmbeddingConfigured(hippoRoot: string): boolean;
+//# sourceMappingURL=provider.d.ts.map

package/dist/{embedding-provider.js → store/embeddings/provider.js}

@@ -1,36 +1,19 @@
-/**
- * Pluggable embedding providers for Hippo.
- *
- * The local `@huggingface/transformers` path stays the zero-DEPENDENCY DEFAULT. Opt-in
- * API providers (OpenAI / Voyage / Cohere) let a user bring a frontier embedder
- * (e.g. text-embedding-3-large) for frontier-class retrieval. They use the native
- * `fetch` global (Node >= 22.16, see package.json engines; NO new dependency) and
- * read their key from a conventional env var. The provider is selected by
- * `config.embeddings.provider` (default `'local'`).
- *
- * Design contract:
- *   - Local provider `id` is the BARE model string; the STORED identity adds a `#t<N>`
- *     embed-text-format suffix (`embeddingIndexIdentity`), so older stores reindex once:
- *     their vectors were computed over path-contaminated text.
- *   - API provider `id` is `${kind}:${model}`; switching to/from an API embedder
- *     (or a dimension change) flips the identity and triggers the existing
- *     reindex-on-change path.
- *   - `resolveEmbeddingProvider` throws on an invalid config (unknown provider,
- *     bad apiBaseUrl); `embedMemory` turns that into a warning. `isAvailable()` is provider-aware
- *     (local -> dependency installed; api -> key present). `embed()` MAY throw on
- *     a hard transport/auth failure so a reindex can abort atomically; hot paths
- *     wrap it and fall back to BM25.
- *
- * The exact request/response shapes for the API providers are documented from each
- * vendor's public embeddings API; they are unit-tested here against a mocked
- * `fetch` and are integration-verified in Workstream C (real API calls are
- * egress-blocked in the build sandbox).
- */
-import { envByName } from './env.js';
-import { getEmbedding, isEmbeddingAvailable, requireLocalPipeline, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './local-embedding.js';
-import { loadConfig } from './config.js';
-import { redactSecretsStrict } from './secret-detect.js';
-import { fetchWithRetry } from './http-retry.js';
+/** Pluggable embedding providers; local `@huggingface/transformers` is the zero-dependency default, OpenAI / Voyage / Cohere are opt-in via native `fetch`.
+ * Local `id` is the bare model string, API `id` is `${kind}:${model}`; the stored identity adds `#t<N>` (`embeddingIndexIdentity`), so changes reindex.
+ * `embed()` MAY throw on hard transport/auth failure so a reindex aborts atomically; hot paths wrap it and fall back to BM25. */
+import { envByName } from '../../util/env.js';
+import { getEmbedding, isEmbeddingAvailable, requireLocalPipeline, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './local.js';
+import { loadConfig } from '../../core/config.js';
+import { errorMessage, log } from '../../util/log.js';
+import { redactSecretsStrict } from '../../util/secret-detect.js';
+import { fetchWithRetry } from '../../util/http-retry.js';
+import { readCappedJson, readCappedText } from '../../util/capped-json.js';
+const ERROR_DETAIL_CHARS = 300;
+// An error body is read for its first lines only; 4x leaves room for multi-byte text.
+const ERROR_BODY_MAX_BYTES = ERROR_DETAIL_CHARS * 4;
+// 16,384 dimensions at 32 bytes a number: four times a 4,096-dimension model.
+const EMBED_REPLY_BYTES_PER_INPUT = 512 * 1024;
+const EMBED_REPLY_BASE_BYTES = 64 * 1024;
 export const API_PROVIDER_KINDS = ['openai', 'voyage', 'cohere'];
 function isApiProviderKind(x) {
     return x === 'openai' || x === 'voyage' || x === 'cohere';
@@ -39,9 +22,8 @@ const DEFAULT_API_BATCH_SIZE = 64;
 /** Per-request timeout for API embedding calls. A provider/proxy that accepts
  *  the connection but never responds must not hang embed/recall indefinitely. */
 const REQUEST_TIMEOUT_MS = 30_000;
-// ---------------------------------------------------------------------------
-// Local provider — wraps the existing zero-dep transformers.js path.
-// ---------------------------------------------------------------------------
+// Under a caller's deadline a longer Retry-After hands the reply back at once; the remote rerankers use the same cap.
+const DEADLINE_RETRY_WAIT_CAP_MS = 2_000;
 class LocalEmbeddingProvider {
     model;
     enabled;
@@ -76,8 +58,7 @@ const API_PROVIDER_SPECS = {
         // OpenAI has no asymmetric query/passage input type for embeddings.
         buildBody: (model, texts) => ({ model, input: texts }),
         extractVectors: (json) => {
-            // SAFETY: OpenAI's documented embeddings response envelope; embedChunk
-            // validates vector count/non-emptiness against the request afterward,
+            // SAFETY: OpenAI's documented embeddings envelope; embedChunk validates vector count and non-emptiness afterward,
             // so a malformed response degrades to [] here and throws there.
             const data = json.data ?? [];
             return data.map((d) => d.embedding ?? []);
@@ -95,8 +76,7 @@ const API_PROVIDER_SPECS = {
             return body;
         },
         extractVectors: (json) => {
-            // SAFETY: Voyage's documented embeddings response envelope; embedChunk
-            // validates vector count/non-emptiness against the request afterward,
+            // SAFETY: Voyage's documented embeddings envelope; embedChunk validates vector count and non-emptiness afterward,
             // so a malformed response degrades to [] here and throws there.
             const data = json.data ?? [];
             return data.map((d) => d.embedding ?? []);
@@ -114,10 +94,8 @@ const API_PROVIDER_SPECS = {
             embedding_types: ['float'],
         }),
         extractVectors: (json) => {
-            // Cohere v2: { embeddings: { float: number[][] } }
-            // SAFETY: matches Cohere's documented v2 response envelope; embedChunk
-            // validates vector count/non-emptiness against the request afterward,
-            // so a malformed response degrades to [] here and throws there.
+            // Cohere v2 shape: { embeddings: { float: number[][] } }
+            // SAFETY: documented v2 envelope; embedChunk validates the vectors afterward, so a malformed response degrades to [] here and throws there.
             const emb = json.embeddings;
             return emb?.float ?? [];
         },
@@ -129,6 +107,13 @@ function redact(text, secret) {
         return text;
     return text.split(secret).join('***');
 }
+/** A cause with the key cut out: the caught error's own text or cause chain can echo the Authorization header. */
+function redactedCause(err, key) {
+    const copy = new Error(redact(errorMessage(err), key));
+    if (err instanceof Error)
+        copy.name = err.name;
+    return copy;
+}
 function l2normalize(v) {
     let norm = 0;
     for (const x of v)
@@ -160,7 +145,7 @@ class ApiEmbeddingProvider {
     isAvailable() {
         return this.enabled && !!envByName(this.keyEnv)?.trim();
     }
-    async embed(texts, role) {
+    async embed(texts, role, call = {}) {
         if (texts.length === 0)
             return [];
         const key = envByName(this.keyEnv)?.trim();
@@ -172,62 +157,74 @@ class ApiEmbeddingProvider {
         const out = [];
         for (let i = 0; i < texts.length; i += this.batchSize) {
             const chunk = texts.slice(i, i + this.batchSize);
-            const vecs = await this.embedChunk(chunk, key, role);
+            const vecs = await this.embedChunk(chunk, key, role, call.signal);
             for (const v of vecs)
                 out.push(v.length > 0 ? l2normalize(v) : v);
         }
         return out;
     }
-    async embedChunk(chunk, key, role) {
+    async embedChunk(chunk, key, role, signal) {
+        const spec = API_PROVIDER_SPECS[this.kind];
+        const resp = await this.postChunk(chunk, key, role, signal);
+        const json = await this.responseJson(resp, key, chunk.length);
+        const vectors = spec.extractVectors(json);
+        // A 200 with the wrong vector count (or any empty/malformed vector) is a provider contract violation, not a per-item miss:
+        // throw so a reindex aborts atomically and the explicit backfill surfaces it, instead of saving []-padded rows.
+        if (vectors.length !== chunk.length) {
+            throw new Error(redact(`${this.kind} embeddings returned ${vectors.length} vectors for ${chunk.length} inputs`, key));
+        }
+        for (let i = 0; i < vectors.length; i++) {
+            if (!vectors[i] || vectors[i].length === 0) {
+                throw new Error(redact(`${this.kind} embeddings returned an empty vector at index ${i}`, key));
+            }
+        }
+        return vectors;
+    }
+    async postChunk(chunk, key, role, signal) {
         const spec = API_PROVIDER_SPECS[this.kind];
         const url = `${this.baseUrl.replace(/\/$/, '')}/${spec.path}`;
-        let resp;
         try {
-            resp = await fetchWithRetry(url, {
+            return await fetchWithRetry(url, {
                 method: 'POST',
                 headers: {
                     'content-type': 'application/json',
                     authorization: `Bearer ${key}`,
                 },
                 body: JSON.stringify(spec.buildBody(this.model, chunk.map(redactSecretsStrict), role)),
-            }, { timeoutMs: REQUEST_TIMEOUT_MS });
+                signal,
+            }, {
+                timeoutMs: REQUEST_TIMEOUT_MS,
+                // Embedding the same text twice changes nothing on the far side, so a dropped connection or a stalled attempt is replayed.
+                retryTransport: true,
+                maxDelayMs: signal ? DEADLINE_RETRY_WAIT_CAP_MS : undefined,
+            });
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(redact(`embedding request to ${this.kind} failed: ${msg}`, key));
+            const msg = errorMessage(err);
+            throw new Error(redact(`embedding request to ${this.kind} failed: ${msg}`, key), { cause: redactedCause(err, key) });
         }
+    }
+    /** The body of an OK reply; any other status, or a body that is not JSON, throws with the key cut out. */
+    async responseJson(resp, key, inputs) {
         if (!resp.ok) {
             let detail = '';
             try {
-                detail = await resp.text();
+                detail = await readCappedText(resp, ERROR_BODY_MAX_BYTES);
             }
             catch {
                 /* ignore body read error */
             }
-            throw new Error(redact(`${this.kind} embeddings HTTP ${resp.status}: ${detail.slice(0, 300)}`, key));
+            throw new Error(redact(`${this.kind} embeddings HTTP ${resp.status}: ${detail.slice(0, ERROR_DETAIL_CHARS)}`, key));
         }
-        let json;
         try {
-            json = await resp.json();
+            return await readCappedJson(resp, EMBED_REPLY_BASE_BYTES + inputs * EMBED_REPLY_BYTES_PER_INPUT);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(redact(`${this.kind} embeddings returned invalid JSON: ${msg}`, key));
+            const msg = errorMessage(err);
+            throw new Error(redact(`${this.kind} embeddings returned invalid JSON: ${msg}`, key), {
+                cause: redactedCause(err instanceof Error && err.cause ? err.cause : err, key)
+            });
         }
-        const vectors = spec.extractVectors(json);
-        // A 200 response with the wrong number of vectors (or any empty/malformed
-        // vector) is a provider/proxy contract violation, NOT a per-item miss. Throw
-        // so a reindex aborts atomically (preserving the prior usable index) and the
-        // explicit backfill surfaces it, instead of silently saving []-padded rows.
-        if (vectors.length !== chunk.length) {
-            throw new Error(redact(`${this.kind} embeddings returned ${vectors.length} vectors for ${chunk.length} inputs`, key));
-        }
-        for (let i = 0; i < vectors.length; i++) {
-            if (!vectors[i] || vectors[i].length === 0) {
-                throw new Error(redact(`${this.kind} embeddings returned an empty vector at index ${i}`, key));
-            }
-        }
-        return vectors;
     }
 }
 function readEmbeddingsConfig(hippoRoot) {
@@ -258,13 +255,8 @@ function validateBaseUrl(url, fallback) {
     }
     return candidate;
 }
-/**
- * Build the active embedding provider from config (or an explicit override).
- * Never throws for a missing key — that surfaces via `isAvailable()` on the hot
- * paths and as a hard error only from the explicit `hippo embed` command. The
- * only hard throw is an invalid config (e.g. an insecure apiBaseUrl), a
- * deliberate loud failure; hot-path callers (search) wrap this in try/catch.
- */
+/** Build the active embedding provider from config (or an explicit override). A missing key never throws here (it surfaces via `isAvailable()`);
+ * only an invalid config (e.g. insecure apiBaseUrl) throws, deliberately loud, so hot-path callers wrap it. */
 export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
     const cfg = readEmbeddingsConfig(hippoRoot);
     const requested = opts.provider ?? cfg.provider ?? 'local';
@@ -291,25 +283,20 @@ export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
         : DEFAULT_API_BATCH_SIZE;
     return new ApiEmbeddingProvider(kind, model, baseUrl, batchSize, enabled);
 }
-/**
- * The reindex identity for the active provider. Use this (NOT resolveEmbeddingModel)
- * everywhere `embeddingModelRequiresReindex` / stored-model comparisons happen.
- */
+/** The reindex identity for the active provider; use it, NOT resolveEmbeddingModel, wherever `embeddingModelRequiresReindex` / stored-model comparisons
+ * happen. */
 export function resolveEmbeddingIdentity(hippoRoot, opts = {}) {
     return resolveEmbeddingProvider(hippoRoot, opts).id;
 }
-/**
- * Provider-aware availability for a store: local -> dependency installed;
- * api -> key present. Use at the call sites that decide whether to embed.
- */
+/** Provider-aware availability for a store (local: dependency installed; api: key present); use where the decision to embed is made. */
 export function isEmbeddingConfigured(hippoRoot) {
     try {
         return resolveEmbeddingProvider(hippoRoot).isAvailable();
     }
-    catch {
-        // Invalid embedding config (e.g. an insecure apiBaseUrl) must not crash the
-        // best-effort ingestion guard — treat it as "not configured" and skip.
+    catch (err) {
+        // An invalid embedding config must not crash the best-effort ingestion guard, so it reads as not configured.
+        log.debug(`embedding config unusable: ${errorMessage(err)}`);
         return false;
     }
 }
-//# sourceMappingURL=embedding-provider.js.map
+//# sourceMappingURL=provider.js.map

package/dist/store/entry-reads.d.ts

@@ -1,83 +1,86 @@
-import type { MemoryEntry } from '../memory.js';
-import { type DatabaseSyncLike } from '../db.js';
-/**
- * Read a memory entry by ID.
- *
- * When `tenantId` is provided, the read is scoped to that tenant (cross-tenant
- * lookups return null). When omitted, no tenant filter is applied — preserves
- * legacy single-tenant callers and the writeEntry/readEntry round-trip.
- */
+import type { MemoryEntry } from '../core/memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+export declare const TENANT_IS = "+tenant_id = ?";
+/** Read a memory entry by ID. With `tenantId` the read is tenant-scoped (cross-tenant returns null); omitted, no tenant filter is applied. */
 export declare function readEntry(hippoRoot: string, id: string, tenantId?: string): MemoryEntry | null;
 /** Ids per `IN (...)` list: far under SQLite's bound-parameter limit, with room for the tenant filter. */
 export declare const ID_CHUNK = 500;
 /** `items` in consecutive slices of at most `size`. */
 export declare function chunked<T>(items: readonly T[], size?: number): T[][];
+/** Answers whether a tenant's rows in this store hold an id: `ids` are looked up now, one query per chunk, and any other id on its first ask. */
+export declare function heldIdLookup(hippoRoot: string, tenantId: string, ids: readonly string[]): (id: string) => boolean;
 /** Rows by id on the caller's handle, one query per chunk; an id missing or in another tenant is absent from the map. */
 export declare function selectEntriesByIds(db: DatabaseSyncLike, ids: readonly string[], tenantId?: string): Map<string, MemoryEntry>;
 /** Direct children of each parent, one query per chunk; each list is in `created ASC, id ASC` order. */
 export declare function selectChildrenByParent(db: DatabaseSyncLike, parentIds: readonly string[], tenantId?: string): Map<string, MemoryEntry[]>;
-/**
- * Batched lookup. Caps at 500 ids per call to keep the IN(?,?,...) clause
- * within SQLite limits. Tenant filter is enforced when `tenantId` is passed.
- * Used by DAG-aware recall to fetch parent summaries for a set of overflowed leaves.
- */
+/** Batched lookup, capped at 500 ids per call to keep IN(?,?,...) within SQLite limits; tenant filter enforced when `tenantId` is passed. */
 export declare function loadEntriesByIds(hippoRoot: string, ids: readonly string[], tenantId?: string): MemoryEntry[];
-/**
- * All `kind='raw'` rows for a given session, tenant-scoped, returned
- * oldest-first. Used by `api.assemble` to walk a session's chronological
- * context. Excludes superseded rows.
- *
- * Cap semantics: when `cap` is provided, the NEWEST `cap` rows are loaded (DESC LIMIT server-side,
- * reversed client-side); ASC + LIMIT would drop the newest rows and break fresh-tail in assemble.
- *
- * Returns `[]` for an empty sessionId. Final order: `created ASC, id ASC`.
- */
+/** All `kind='raw'` rows for a session, tenant-scoped, oldest-first, excluding superseded; `[]` for an empty sessionId.
+ * With `cap`, the NEWEST rows are loaded (DESC LIMIT, reversed client-side); ASC + LIMIT would drop the newest and break fresh-tail in assemble. */
 export declare function loadSessionRawMemories(hippoRoot: string, sessionId: string, tenantId?: string, cap?: number, origins?: readonly string[]): MemoryEntry[];
-/**
- * Pre-cap, scope-aware row count for a session. Lets `assemble` report
- * the full session size even when `rowCap` truncates the loaded window,
- * WITHOUT leaking rows the caller wouldn't have been allowed to load.
- *
- * An unscoped COUNT would let a no-scope caller infer private rows by comparing `totalRaw`
- * against `items.length`, so this SQL-encodes the default-deny rule `passesScopeFilterForRecall` applies in TS:
- *   - explicit scope passed: exact-match
- *   - no scope: `scopeAdmitSql`'s default deny, which admits `ownScope`, the caller's personal scope.
- *
- * `tenantId` is optional for back-compat. Pass `undefined` only when
- * intentionally counting cross-tenant; `assemble()` passes `ctx.tenantId`.
- */
+/** Pre-cap, scope-aware row count for a session, so `assemble` reports the full size without leaking rows the caller could not load. Mirrors
+ * `passesScopeFilterForRecall`'s default-deny: explicit scope matches exactly, none admits only `ownScope`. `tenantId` undefined counts cross-tenant. */
 export declare function countSessionRawMemories(hippoRoot: string, sessionId: string, tenantId?: string, scope?: string, ownScope?: string, origins?: readonly string[]): number;
-/**
- * Last N kind='raw' memories by `created` desc. Tenant scoped. When
- * `sessionId` is supplied, also constrains to a specific session — that
- * is the correct shape for "what did I just see in THIS session."
- *
- * Without `sessionId`, concurrent sessions in a tenant surface each other's rows as fresh tail;
- * pass undefined only for "anything new across the whole tenant".
- *
- * Bounded count cap at 200 — beyond that the caller should filter via
- * tags/scope rather than time-windowed recall.
- *
- * The tenant-wide shape is the back-compat default but discouraged; `api.recall` throws
- * `RecallContractError` for it when `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1` is set.
- */
+/** Last N kind='raw' memories by `created` desc, tenant-scoped, max 200; pass `sessionId` or concurrent sessions show up in each other's fresh tail.
+ * The tenant-wide shape is discouraged: `api.recall` throws `RecallContractError` for it when `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`. */
 export declare function loadFreshRawMemories(hippoRoot: string, count: number, tenantId?: string, sessionId?: string, origins?: readonly string[]): MemoryEntry[];
-/**
- * Direct DAG children of a parent summary. Tenant scoped. Returns only rows
- * whose `dag_parent_id` matches `parentId`; does NOT walk recursively.
- */
-export declare function loadChildrenOf(hippoRoot: string, parentId: string, tenantId?: string): MemoryEntry[];
-/**
- * Load all entries from SQLite.
- *
- * When `tenantId` is provided, results are scoped to that tenant. Omitting it
- * yields all rows (legacy behavior used by consolidate/autolearn etc.). Recall
- * paths that surface results to a user MUST pass a resolved tenant.
- */
+/** Load all entries from SQLite; omitting `tenantId` yields all rows (legacy). Recall paths that surface results to a user MUST pass a resolved tenant. */
 export declare function loadAllEntries(hippoRoot: string, tenantId?: string): MemoryEntry[];
+/** Every tenant's memory ids in loadAllEntries' order, for a caller that reads the rows a page at a time instead of holding them all. */
+export declare function loadAllEntryIds(hippoRoot: string): string[];
+export interface EntriesWithBase {
+    entries: MemoryEntry[];
+    base: {
+        get(id: string): MemoryEntry | undefined;
+    };
+}
+/** Every entry plus a by-id lookup of each as loaded, rebuilt from its row on first use, so no deep copy of the store is kept. */
+export declare function loadAllEntriesWithBase(hippoRoot: string): EntriesWithBase;
 /** Every memory row on an open connection, so a caller can read inside its own transaction. */
 export declare function selectAllEntries(db: DatabaseSyncLike, tenantId?: string): MemoryEntry[];
 /** Live rows whose source starts with `prefix`, on the caller's handle; LIKE folds case, so the prefix is checked again exactly. */
 export declare function selectLiveEntriesBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): MemoryEntry[];
 export declare function loadContentsWithTag(hippoRoot: string, tenantId: string, tag: string, origins?: readonly string[]): string[];
+export interface VaultRawRow {
+    id: string;
+    artifact_ref: string;
+    tags_json: string;
+    scope: string | null;
+}
+/** Live raw rows whose artifact_ref matches a LIKE pattern, for one tenant; the store is set up first when it is new. */
+export declare function loadVaultRawRows(hippoRoot: string, likeParam: string, tenantId: string): VaultRawRow[];
+export interface PreviewRow {
+    id: string;
+    content: string;
+    source: string | null;
+    confidence: MemoryEntry['confidence'] | null;
+    extracted_from: string | null;
+    dag_level: number | null;
+    tags_json: string | null;
+}
+/** Reads memories from a store whose schema may predate some columns; `columns` is the table's real column set. */
+export declare function selectPreviewRows(db: DatabaseSyncLike, columns: ReadonlySet<string>, tenantId: string): PreviewRow[];
+/** True when a memory row, of any tenant, already holds `id`. */
+export declare function entryIdTakenAt(db: DatabaseSyncLike, id: string): boolean;
+/** The text, tenant and scope of memory `id`, or undefined when no row holds it. */
+export declare function entryRejectRowAt(db: DatabaseSyncLike, id: string): {
+    content: string;
+    tenant_id: string;
+    scope: string | null;
+} | undefined;
+export declare function objectMemoryRowsAt(db: DatabaseSyncLike): Array<{
+    memory_id: string;
+    status: string;
+}>;
+/** Live rows of a tenant whose source does not start with `sourcePrefix`; `origins` (global store only) limits them to user-global rows and those projects. */
+export declare function selectRowsOutsideSourcePrefixAt(db: DatabaseSyncLike, tenantId: string, sourcePrefix: string, origins: readonly string[] | null): Array<{
+    id: string;
+    content: string;
+    source: string;
+}>;
+/** Content of a tenant's live rows written by `source` and tagged `tag` that no extraction produced,
+ * in loadAllEntries' order and in every scope; `exceptSessionId` drops one session's own rows. */
+export declare function loadLiveContentsBySourceAndTag(hippoRoot: string, tenantId: string, source: string, tag: string, exceptSessionId: string): string[];
+/** Every tenant's distilled rows nothing has superseded, in loadAllEntries' order: the rows that can be each other's duplicate. */
+export declare function loadCurrentDistilledEntries(hippoRoot: string): MemoryEntry[];
 //# sourceMappingURL=entry-reads.d.ts.map