hippo-memory 1.60.0 → 1.62.0

package/dist/incidents.js

@@ -27,11 +27,12 @@
  */
 import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
 import { assertTenantId } from './tenant.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
 import { objectHalfLifeDays } from './half-life-migration.js';
+import { keysetAfter } from './keyset.js';
 export const VALID_INCIDENT_STATES = new Set([
     'open',
     'resolved',
@@ -76,6 +77,50 @@ const INCIDENT_COLS = `
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+// Validate every linked receipt BEFORE inserting the row. Each must be a
+// memory in the SAME tenant; a cross-tenant or nonexistent id rejects the
+// whole write rather than recording an unverifiable receipt.
+function validateLinkedMemoryIds(db, tenantId, linkInput) {
+    const validated = [];
+    for (const linkId of linkInput) {
+        // SAFETY: row shape matches the single `id` column named in the SELECT above.
+        const exists = db.prepare(`SELECT id FROM memories WHERE id = ? AND tenant_id = ?`).get(linkId, tenantId);
+        if (!exists) {
+            throw new NotFoundError(`saveIncident: linked memory ${linkId} not found for tenant ${tenantId}`);
+        }
+        validated.push(linkId);
+    }
+    return validated;
+}
+/** The afterWrite body: link validation, INSERT, reload, open audit, all in one SAVEPOINT. */
+function writeIncidentRow(db, memoryId, tenantId, opts, actor, now) {
+    const validated = validateLinkedMemoryIds(db, tenantId, opts.linkedMemoryIds ?? []);
+    const result = db.prepare(`
+    INSERT INTO incidents(
+      memory_id, tenant_id, incident_text, context,
+      status, resolution_text, resolved_at, closed_at, linked_memory_ids, created_at
+    ) VALUES (?, ?, ?, ?, 'open', NULL, NULL, NULL, ?, ?)
+  `).run(memoryId, tenantId, opts.incidentText, opts.context ?? null, JSON.stringify(validated), now);
+    const incidentId = Number(result.lastInsertRowid ?? 0);
+    // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
+    const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ?`)
+        .get(incidentId);
+    if (!row)
+        throw new Error('saveIncident: failed to reload saved incident row');
+    // GDPR-light metadata: id + flag only, no incident_text.
+    appendAuditEvent(db, {
+        tenantId,
+        actor,
+        op: 'incident_open',
+        targetId: String(incidentId),
+        metadata: {
+            incident_id: incidentId,
+            has_context: opts.context !== undefined && opts.context !== null && opts.context !== '',
+            linked_memory_count: validated.length,
+        },
+    });
+    return row;
+}
 /**
  * Create an incident. Writes the memory mirror + the incidents row atomically
  * inside writeEntry's SAVEPOINT 'write_entry'.
@@ -105,50 +150,13 @@ export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
         baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
         tenantId,
     });
-    const linkInput = opts.linkedMemoryIds ?? [];
     // Populated inside afterWrite so the linked-id validation, the INSERT, and the
     // memory write all share one SAVEPOINT.
     let savedRow;
     writeEntry(hippoRoot, mem, {
         actor,
         afterWrite: (db, memoryId) => {
-            // Validate every linked receipt BEFORE inserting the row. Each must be a
-            // memory in the SAME tenant; a cross-tenant or nonexistent id rejects the
-            // whole write rather than recording an unverifiable receipt.
-            const validated = [];
-            for (const linkId of linkInput) {
-                // SAFETY: row shape matches the single `id` column named in the SELECT above.
-                const exists = db.prepare(`SELECT id FROM memories WHERE id = ? AND tenant_id = ?`).get(linkId, tenantId);
-                if (!exists) {
-                    throw new NotFoundError(`saveIncident: linked memory ${linkId} not found for tenant ${tenantId}`);
-                }
-                validated.push(linkId);
-            }
-            const result = db.prepare(`
-        INSERT INTO incidents(
-          memory_id, tenant_id, incident_text, context,
-          status, resolution_text, resolved_at, closed_at, linked_memory_ids, created_at
-        ) VALUES (?, ?, ?, ?, 'open', NULL, NULL, NULL, ?, ?)
-      `).run(memoryId, tenantId, opts.incidentText, opts.context ?? null, JSON.stringify(validated), now);
-            const incidentId = Number(result.lastInsertRowid ?? 0);
-            // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
-            const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ?`)
-                .get(incidentId);
-            if (!row)
-                throw new Error('saveIncident: failed to reload saved incident row');
-            savedRow = row;
-            // GDPR-light metadata: id + flag only, no incident_text.
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'incident_open',
-                targetId: String(incidentId),
-                metadata: {
-                    incident_id: incidentId,
-                    has_context: opts.context !== undefined && opts.context !== null && opts.context !== '',
-                    linked_memory_count: validated.length,
-                },
-            });
+            savedRow = writeIncidentRow(db, memoryId, tenantId, opts, actor, now);
         },
     });
     if (!savedRow) {
@@ -286,6 +294,7 @@ export function loadIncidentById(hippoRoot, tenantId, id) {
 export function loadIncidents(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadIncidents', tenantId);
     const limit = opts.limit ?? 100;
+    const after = keysetAfter('created_at', 'id', opts.after);
     const db = openHippoDb(hippoRoot);
     try {
         let rows;
@@ -296,19 +305,19 @@ export function loadIncidents(hippoRoot, tenantId, opts = {}) {
             // SAFETY: rows' shape matches the columns named in INCIDENT_COLS above.
             rows = db.prepare(`
         SELECT ${INCIDENT_COLS} FROM incidents
-        WHERE tenant_id = ? AND status = ?
+        WHERE tenant_id = ? AND status = ?${after.sql}
         ORDER BY created_at DESC, id DESC
         LIMIT ?
-      `).all(tenantId, opts.status, limit);
+      `).all(tenantId, opts.status, ...after.params, limit);
         }
         else {
             // SAFETY: rows' shape matches the columns named in INCIDENT_COLS above.
             rows = db.prepare(`
         SELECT ${INCIDENT_COLS} FROM incidents
-        WHERE tenant_id = ?
+        WHERE tenant_id = ?${after.sql}
         ORDER BY created_at DESC, id DESC
         LIMIT ?
-      `).all(tenantId, limit);
+      `).all(tenantId, ...after.params, limit);
         }
         return rows.map(rowToIncident);
     }

package/dist/index.d.ts

@@ -5,22 +5,41 @@ import { type CreateMemoryOptions, type MemoryEntry } from './memory.js';
 export { MemoryEntry, Layer, EmotionalValence, ConfidenceLevel, DecayOptions, calculateStrength, resolveConfidence, confidenceFacets, type ConfidenceFacets, applyOutcome, generateId, computeSchemaFit } from './memory.js';
 /** Published signature, so `baseHalfLifeDays` stays optional here; hippo's own writers use the strict one in memory.ts. */
 export declare function createMemory(content: string, options?: Partial<CreateMemoryOptions>): MemoryEntry;
-export { search, hybridSearch, physicsSearch, estimateTokens, textOverlap, explainMatch, detectTemporalDirection, temporalBoost, computeTemporalRange, SearchResult, MatchExplanation } from './search.js';
-export { tokenize } from './tokenize.js';
+export { search } from './search/bm25-search.js';
+export { hybridSearch } from './search/hybrid.js';
+export { physicsSearch } from './search/physics-search.js';
+export { explainMatch, MatchExplanation } from './search/explain.js';
+export { detectTemporalDirection, temporalBoost, computeTemporalRange } from './search/temporal.js';
+export { SearchResult } from './search/types.js';
+export { estimateTokens } from './token-ledger.js';
+export { tokenize, textOverlap } from './tokenize.js';
 export { markRetrieved } from './memory.js';
 export { multihopSearch } from './multihop.js';
 export { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS, type GraphExpandOpts } from './graph-recall.js';
-export { initStore, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, writeEntry, readEntry, deleteEntry, loadIndex, rebuildIndex, saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, replaceDetectedConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, loadSessionDecayContext, SessionDecayContext, } from './store.js';
+export { initStore } from './store/open.js';
+export { writeEntry } from './store/entry-writes.js';
+export { loadAllEntries, readEntry } from './store/entry-reads.js';
+export { deleteEntry } from './store/delete-and-batch.js';
+export { loadSearchEntries, loadRecallSearchEntries } from './store/search-rows.js';
+export { loadIndex, rebuildIndex, loadSessionDecayContext, SessionDecayContext } from './store/index-and-stats.js';
+export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, } from './store/sessions.js';
+export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';
+export { saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, } from './store/handoffs.js';
 export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store-cards.js';
 export { SessionHandoff, HandoffOutcome, HandoffEvidence, isHandoffOutcome } from './handoff.js';
 export { Card, CardStatus, CardRun, CardComment, CardTransitions, isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
-export { consolidate, ConsolidationResult } from './consolidate.js';
+export { consolidate } from './consolidate/sleep.js';
+export { ConsolidationResult } from './consolidate/run.js';
 export { strengthBucket } from './dedupe.js';
-export { isEmbeddingAvailable, getEmbedding, cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
+export { isEmbeddingAvailable, getEmbedding } from './local-embedding.js';
+export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
 export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, } from './autolearn.js';
 export { getGlobalRoot, initGlobal, promoteToGlobal, searchBoth, searchBothHybrid, syncGlobalToLocal, HybridSearchOptions, transferScore, shareMemory, listPeers, autoShare, } from './shared.js';
 export { wmPush, wmRead, wmClear, wmFlush, WorkingMemoryItem, WM_MAX_ENTRIES, } from './working-memory.js';
-export { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, importVault, importEntries, ImportResult, ImportOptions, } from './importers.js';
+export { importChatGPT, importClaude, importCursor, importGenericFile, } from './importers/sources.js';
+export { importMarkdown } from './importers/markdown.js';
+export { importVault } from './importers/vault.js';
+export { importEntries, ImportResult, ImportOptions } from './importers/core.js';
 export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval-suite.js';
 export { computeSalience, SalienceDecision, SalienceResult, SalienceOptions, } from './salience.js';
 export { computeAmbientState, renderAmbientSummary, formatAmbientVector, AmbientState, } from './ambient.js';

package/dist/index.js

@@ -7,22 +7,36 @@ export { Layer, calculateStrength, resolveConfidence, confidenceFacets, applyOut
 export function createMemory(content, options = {}) {
     return createStoreMemory(content, { ...options, baseHalfLifeDays: options.baseHalfLifeDays ?? DEFAULT_HALF_LIFE_DAYS });
 }
-export { search, hybridSearch, physicsSearch, estimateTokens, textOverlap, explainMatch, detectTemporalDirection, temporalBoost, computeTemporalRange } from './search.js';
-export { tokenize } from './tokenize.js';
+export { search } from './search/bm25-search.js';
+export { hybridSearch } from './search/hybrid.js';
+export { physicsSearch } from './search/physics-search.js';
+export { explainMatch } from './search/explain.js';
+export { detectTemporalDirection, temporalBoost, computeTemporalRange } from './search/temporal.js';
+export { estimateTokens } from './token-ledger.js';
+export { tokenize, textOverlap } from './tokenize.js';
 export { markRetrieved } from './memory.js';
 export { multihopSearch } from './multihop.js';
 export { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
-export { initStore, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, writeEntry, readEntry, deleteEntry, loadIndex, rebuildIndex, saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, replaceDetectedConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, loadSessionDecayContext, } from './store.js';
+export { initStore } from './store/open.js';
+export { writeEntry } from './store/entry-writes.js';
+export { loadAllEntries, readEntry } from './store/entry-reads.js';
+export { deleteEntry } from './store/delete-and-batch.js';
+export { loadSearchEntries, loadRecallSearchEntries } from './store/search-rows.js';
+export { loadIndex, rebuildIndex, loadSessionDecayContext } from './store/index-and-stats.js';
+export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, } from './store/sessions.js';
+export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';
+export { saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, } from './store/handoffs.js';
 export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store-cards.js';
 // Feature 5: Session handoff
 export { isHandoffOutcome } from './handoff.js';
 // W2a: work-queue cards
 export { isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
-export { consolidate } from './consolidate.js';
+export { consolidate } from './consolidate/sleep.js';
 // Announced public in CHANGELOG 1.26.3 but never re-exported; the rest of dedupe.js stays internal.
 export { strengthBucket } from './dedupe.js';
 // Feature 1: Embedding search
-export { isEmbeddingAvailable, getEmbedding, cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
+export { isEmbeddingAvailable, getEmbedding } from './local-embedding.js';
+export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
 // Feature 2: Auto-learn from errors
 export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, } from './autolearn.js';
 // Feature 3: Cross-agent shared memory
@@ -30,7 +44,10 @@ export { getGlobalRoot, initGlobal, promoteToGlobal, searchBoth, searchBothHybri
 // Feature 5: Working memory
 export { wmPush, wmRead, wmClear, wmFlush, WM_MAX_ENTRIES, } from './working-memory.js';
 // Feature 4: Memory importers
-export { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, importVault, importEntries, } from './importers.js';
+export { importChatGPT, importClaude, importCursor, importGenericFile, } from './importers/sources.js';
+export { importMarkdown } from './importers/markdown.js';
+export { importVault } from './importers/vault.js';
+export { importEntries } from './importers/core.js';
 // Feature eval suite
 export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval-suite.js';
 // Pineal gland: salience gate

package/dist/invalidation.js

@@ -1,4 +1,5 @@
-import { loadAllEntries, readEntry, writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
+import { loadAllEntries, readEntry } from './store/entry-reads.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { CHURN_STALE_TAG } from './memory.js';
 import { GitReadError, gitLsFilesAtHead, fetchChurnWindowLog, gitGrepPresence, resolveCommitBefore, packageScriptsAt, } from './churn-git.js';

package/dist/judgment.js

@@ -1,6 +1,7 @@
 /** Typed judgment over capture candidates via TypeSafe's Jev (System One).
  *  Regex picks WHAT is a candidate; it cannot say what is worth keeping, so
  *  every captured memory currently lands on a flat schema_fit of 0.5. */
+import { envTypesafeApiKey } from './env.js';
 import { fetchWithRetry } from './http-retry.js';
 import { log } from './log.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
@@ -37,7 +38,7 @@ const KINDS = ['error', 'decision', 'convention', 'preference', 'trivia'];
 const VALENCES = ['critical', 'negative', 'positive', 'neutral'];
 /** Absent key means hippo keeps its pre-Jev behaviour and makes no HTTP call. */
 export function judgmentApiKey() {
-    const key = process.env.TYPESAFE_API_KEY?.trim();
+    const key = envTypesafeApiKey()?.trim();
     return key ? key : undefined;
 }
 function oneOf(value, allowed) {

package/dist/keyset.d.ts

@@ -0,0 +1,13 @@
+/** The sort key and id of the last row a page returned. */
+export interface KeysetPosition {
+    readonly key: string | number;
+    readonly id: string | number;
+}
+/** A WHERE fragment and the params it binds. */
+export interface KeysetClause {
+    sql: string;
+    params: Array<string | number>;
+}
+/** An ` AND ...` WHERE fragment and its params selecting rows strictly after `after`; empty when `after` is unset. */
+export declare function keysetAfter(sortCol: string, idCol: string, after: KeysetPosition | undefined): KeysetClause;
+//# sourceMappingURL=keyset.d.ts.map

package/dist/keyset.js

@@ -0,0 +1,8 @@
+// Keyset paging for list queries ordered by (sort key DESC, id DESC), so a page never skips or repeats a row when rows arrive between requests.
+/** An ` AND ...` WHERE fragment and its params selecting rows strictly after `after`; empty when `after` is unset. */
+export function keysetAfter(sortCol, idCol, after) {
+    if (!after)
+        return { sql: '', params: [] };
+    return { sql: ` AND (${sortCol}, ${idCol}) < (?, ?)`, params: [after.key, after.id] };
+}
+//# sourceMappingURL=keyset.js.map

package/dist/local-embedding.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
+/** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
+export declare function poolingFor(model: string): 'cls' | 'mean';
+/** `query` is search input, `passage` is a document being indexed; no role means no prefix on any model. */
+export type EmbeddingRole = 'query' | 'passage';
+/** e5 models only match a query to a passage when each side carries its trained prefix. */
+export declare function prefixFor(model: string, role?: EmbeddingRole): string;
+/** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
+export declare function isEmbeddingAvailable(): boolean;
+export declare function resolveEmbeddingModel(hippoRoot: string, explicitModel?: string): string;
+/** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
+export declare function getEmbedding(text: string, model?: string, role?: EmbeddingRole): Promise<number[]>;
+//# sourceMappingURL=local-embedding.d.ts.map

package/dist/local-embedding.js

@@ -0,0 +1,165 @@
+// The local Transformers.js embedder, a leaf so embedding-provider.ts can wrap it without importing embeddings.ts.
+import { envModelCache } from './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';
+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.
+const _pipelineInstances = new Map();
+const _pipelineLoading = new Map();
+export const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
+/** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
+export function poolingFor(model) {
+    return /\bbge\b/i.test(model) ? 'cls' : 'mean';
+}
+/** e5 models only match a query to a passage when each side carries its trained prefix. */
+export function prefixFor(model, role) {
+    if (!role)
+        return '';
+    if (/\be5\b/i.test(model)) {
+        return role === 'query' ? 'query: ' : 'passage: ';
+    }
+    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)
+        return _embeddingAvailable;
+    try {
+        _require.resolve('@xenova/transformers');
+        _embeddingAvailable = true;
+        return true;
+    }
+    catch {
+        // fall through
+    }
+    try {
+        _require.resolve('@huggingface/transformers');
+        _embeddingAvailable = true;
+        return true;
+    }
+    catch {
+        // fall through
+    }
+    _embeddingAvailable = false;
+    return false;
+}
+// Importing both packages loads two incompatible onnxruntime-node builds whose finalizers can double-free on exit,
+// so pick one first: the maintained package hippo ships, with Xenova only as a fallback a user installed.
+function resolveTransformersPackage() {
+    try {
+        _require.resolve('@huggingface/transformers');
+        return '@huggingface/transformers';
+    }
+    catch {
+        // fall through
+    }
+    try {
+        _require.resolve('@xenova/transformers');
+        return '@xenova/transformers';
+    }
+    catch {
+        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)
+            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) {
+            log.debug(`transformers import failed (${pkg}): ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        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()?.trim();
+        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) {
+            log.debug(`embedding pipeline load failed (${model}): ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        finally {
+            _pipelineLoading.delete(model);
+        }
+    })();
+    _pipelineLoading.set(model, loading);
+    return loading;
+}
+export function resolveEmbeddingModel(hippoRoot, explicitModel) {
+    const direct = explicitModel?.trim();
+    if (direct)
+        return direct;
+    try {
+        const configured = loadConfig(hippoRoot).embeddings.model?.trim();
+        if (configured)
+            return configured;
+    }
+    catch {
+        // Fall back to the default model when config cannot be read.
+    }
+    return DEFAULT_EMBEDDING_MODEL;
+}
+/** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
+export async function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role) {
+    if (!isEmbeddingAvailable())
+        return [];
+    try {
+        const pipe = await loadPipeline(model);
+        if (!pipe)
+            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)}`);
+        return [];
+    }
+}
+//# sourceMappingURL=local-embedding.js.map

package/dist/log.d.ts

@@ -12,13 +12,20 @@ export declare function isLevelEnabled(level: LogLevel): boolean;
 export declare function formatLogLine(level: LogLevel, message: string, fields?: LogFields): string;
 /** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
 declare function once(key: string, level: LogLevel, message: string, fields?: LogFields): void;
+/** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable without flooding stderr. */
+declare function warnThenDebug(key: string, message: string, fields?: LogFields): void;
+/** The class name and stack of a thrown value, as log fields; a non-Error throw has no stack. */
+export declare function errorFields<E>(err: E): LogFields;
 export declare const log: {
     readonly error: (message: string, fields?: LogFields) => void;
     readonly warn: (message: string, fields?: LogFields) => void;
     readonly info: (message: string, fields?: LogFields) => void;
     readonly debug: (message: string, fields?: LogFields) => void;
     readonly once: typeof once;
+    readonly warnThenDebug: typeof warnThenDebug;
 };
+/** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause enrichment). */
+export declare function errorMessage(cause: unknown): string;
 /** Test hook: forget which once-keys have fired. */
 export declare function resetLogOnce(): void;
 export {};

package/dist/log.js

@@ -1,11 +1,12 @@
 /** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. */
+import { envLogLevel } from './env.js';
 const RANK = { error: 0, warn: 1, info: 2, debug: 3 };
 function isLogLevel(value) {
     return Object.hasOwn(RANK, value);
 }
 /** The active threshold, read on every call so a test or a long-lived server can change it without a restart. */
 export function logThreshold() {
-    const raw = process.env.HIPPO_LOG?.trim().toLowerCase() ?? '';
+    const raw = envLogLevel();
     return isLogLevel(raw) ? raw : 'warn';
 }
 export function isLevelEnabled(level) {
@@ -34,13 +35,30 @@ function once(key, level, message, fields) {
     onceKeys.add(key);
     write(level, message, fields);
 }
+/** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable without flooding stderr. */
+function warnThenDebug(key, message, fields) {
+    const level = onceKeys.has(key) ? 'debug' : 'warn';
+    onceKeys.add(key);
+    write(level, message, fields);
+}
+/** The class name and stack of a thrown value, as log fields; a non-Error throw has no stack. */
+export function errorFields(err) {
+    if (!(err instanceof Error))
+        return { errorClass: 'NonError' };
+    return { errorClass: err.constructor.name, stack: err.stack };
+}
 export const log = {
     error: (message, fields) => write('error', message, fields),
     warn: (message, fields) => write('warn', message, fields),
     info: (message, fields) => write('info', message, fields),
     debug: (message, fields) => write('debug', message, fields),
     once,
+    warnThenDebug,
 };
+/** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause enrichment). */
+export function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
 /** Test hook: forget which once-keys have fired. */
 export function resetLogOnce() {
     onceKeys.clear();

package/dist/mcp/admin-tools.d.ts

@@ -0,0 +1,8 @@
+import { type ToolCall } from './protocol.js';
+export declare function runPredictBaserateTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+export declare function runStatusTool({ hippoRoot, config, tenantId }: ToolCall): string;
+export declare function runConflictsTool({ hippoRoot, tenantId }: ToolCall): string;
+export declare function runResolveTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+export declare function runShareTool({ args, hippoRoot, tenantId }: ToolCall): string;
+export declare function runPeersTool({ tenantId }: ToolCall): string;
+//# sourceMappingURL=admin-tools.d.ts.map