hippo-memory 1.40.0 → 1.42.0

package/dist/src/index.js

@@ -5,11 +5,11 @@ export { Layer, calculateStrength, resolveConfidence, confidenceFacets, createMe
 export { search, hybridSearch, physicsSearch, markRetrieved, estimateTokens, textOverlap, tokenize, explainMatch, detectTemporalDirection, temporalBoost, computeTemporalRange } from './search.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, createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, blockCard, reviewCard, completeCard, addCardComment, loadLatestHandoffForCard, } from './store.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, createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store.js';
 // Feature 5: Session handoff
 export { isHandoffOutcome } from './handoff.js';
 // W2a: work-queue cards
-export { isCardStatus, CARD_TRANSITIONS } from './card.js';
+export { isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
 export { consolidate } from './consolidate.js';
 // Announced public in CHANGELOG 1.26.3 but never re-exported; the rest of dedupe.js stays internal.
 export { strengthBucket } from './dedupe.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAe,KAAK,EAAmD,iBAAiB,EAAE,iBAAiB,EAAE,gBAAgB,EAAyB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3O,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,uBAAuB,EAAE,aAAa,EAAE,oBAAoB,EAAkC,MAAM,aAAa,CAAC;AACpO,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,qBAAqB,EAAwB,MAAM,mBAAmB,CAAC;AAC7G,OAAO,EACL,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EAEvB,UAAU,EACV,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,UAAU,EACV,YAAY,EACZ,cAAc,EACd,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,6BAA6B;AAC7B,OAAO,EAAmD,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjG,wBAAwB;AACxB,OAAO,EAA2D,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACpH,OAAO,EAAE,WAAW,EAAuB,MAAM,kBAAkB,CAAC;AACpE,oGAAoG;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,8BAA8B;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAExB,uCAAuC;AACvC,OAAO,EACL,aAAa,EACb,UAAU,EACV,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EAEjB,aAAa,EACb,WAAW,EACX,SAAS,EACT,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,4BAA4B;AAC5B,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,OAAO,EAEP,cAAc,GACf,MAAM,qBAAqB,CAAC;AAE7B,8BAA8B;AAC9B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,aAAa,GAGd,MAAM,gBAAgB,CAAC;AAExB,qBAAqB;AACrB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,8BAA8B;AAC9B,OAAO,EACL,eAAe,GAIhB,MAAM,eAAe,CAAC;AAEvB,qCAAqC;AACrC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GAEpB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAe,KAAK,EAAmD,iBAAiB,EAAE,iBAAiB,EAAE,gBAAgB,EAAyB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3O,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,uBAAuB,EAAE,aAAa,EAAE,oBAAoB,EAAkC,MAAM,aAAa,CAAC;AACpO,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,qBAAqB,EAAwB,MAAM,mBAAmB,CAAC;AAC7G,OAAO,EACL,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EAEvB,UAAU,EACV,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,SAAS,EACT,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,6BAA6B;AAC7B,OAAO,EAAmD,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjG,wBAAwB;AACxB,OAAO,EAA2D,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACnI,OAAO,EAAE,WAAW,EAAuB,MAAM,kBAAkB,CAAC;AACpE,oGAAoG;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,8BAA8B;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAExB,uCAAuC;AACvC,OAAO,EACL,aAAa,EACb,UAAU,EACV,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EAEjB,aAAa,EACb,WAAW,EACX,SAAS,EACT,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,4BAA4B;AAC5B,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,OAAO,EAEP,cAAc,GACf,MAAM,qBAAqB,CAAC;AAE7B,8BAA8B;AAC9B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,aAAa,GAGd,MAAM,gBAAgB,CAAC;AAExB,qBAAqB;AACrB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,8BAA8B;AAC9B,OAAO,EACL,eAAe,GAIhB,MAAM,eAAe,CAAC;AAEvB,qCAAqC;AACrC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GAEpB,MAAM,cAAc,CAAC"}

package/dist/src/rerankers/cross-encoder.js

@@ -1,48 +1,46 @@
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 const MODEL_NAME = 'Xenova/ms-marco-MiniLM-L-6-v2';
-// Use Function constructor to bypass TypeScript static module resolution
-// for optional peer dependencies that may not be installed (mirrors the
-// pattern in src/embeddings.ts).
-// SAFETY: this declares the contract we require from the dynamically
-// imported package (a `pipeline` factory, top-level or under `default`);
-// loadTransformersModule validates the resolved value is callable via
-// isPipelineFactory before it is ever invoked.
-const _dynImport = new Function('s', 'return import(s)');
 const _require = createRequire(import.meta.url);
 const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
+// Returns the ESM entry URL, the same build src/embeddings.ts imports. A
+// require-style resolve picks the CommonJS build and puts a second copy of
+// the library, with its own ONNX sessions, in the process.
 function resolveTransformersPackage() {
     for (const name of TRANSFORMERS_PACKAGES) {
         try {
-            _require.resolve(name);
-            return name;
+            return import.meta.resolve(name);
         }
         catch {
-            // Try the legacy fallback only when the preferred package is not installed.
+            // import.meta.resolve is missing under some module runners (vitest's
+            // included); fall through to the require-based resolve there.
+            try {
+                return pathToFileURL(_require.resolve(name)).href;
+            }
+            catch {
+                // Try the legacy fallback only when the preferred package is not installed.
+            }
         }
     }
     return null;
 }
-function isPipelineFactory(value) {
-    return typeof value === 'function';
-}
 async function loadTransformersModule() {
     // Import one backend only. Loading both native ONNX runtimes in one process
     // can abort during finalization; Hugging Face is the maintained default.
-    const name = resolveTransformersPackage();
-    if (!name)
+    const url = resolveTransformersPackage();
+    if (!url)
         return null;
     try {
-        const mod = await _dynImport(name);
-        const pipeline = mod.pipeline ?? mod.default?.pipeline;
-        return isPipelineFactory(pipeline)
-            ? { pipeline }
-            : null;
+        const mod = await import(/* @vite-ignore */ url);
+        const tok = mod.AutoTokenizer ?? mod.default?.AutoTokenizer;
+        const seq = mod.AutoModelForSequenceClassification ?? mod.default?.AutoModelForSequenceClassification;
+        return tok && seq ? { AutoTokenizer: tok, AutoModelForSequenceClassification: seq } : null;
     }
     catch {
         return null;
     }
 }
-let cachedPipeline = null;
+let pipelineLoading = null;
 let warnedOnFallback = false;
 /**
  * True if a Transformers.js backend is importable. Note: this does NOT confirm
@@ -53,40 +51,55 @@ let warnedOnFallback = false;
 export async function isCrossEncoderAvailable() {
     return (await loadTransformersModule()) !== null;
 }
-async function loadPipeline() {
-    if (cachedPipeline)
-        return cachedPipeline;
+// NOT the text-classification pipeline: this model is a num_labels=1
+// regression head, and that pipeline softmaxes a length-1 logit vector, which
+// is identically 1.0 for every input. Read the logit, then squash it.
+async function buildPipeline() {
     try {
         const mod = await loadTransformersModule();
         if (!mod)
             return null;
-        const p = await mod.pipeline('text-classification', MODEL_NAME);
-        cachedPipeline = async (query, candidate) => {
-            const out = await p(`${query} [SEP] ${candidate}`);
-            return Array.isArray(out) ? out : [out];
+        const [tokenizer, model] = await Promise.all([
+            mod.AutoTokenizer.from_pretrained(MODEL_NAME),
+            mod.AutoModelForSequenceClassification.from_pretrained(MODEL_NAME),
+        ]);
+        return async (query, candidate) => {
+            const inputs = await tokenizer(query, {
+                text_pair: candidate,
+                padding: true,
+                truncation: true,
+            });
+            const { logits } = await model(inputs);
+            const score = 1 / (1 + Math.exp(-Number(logits.data[0])));
+            // NaN would make the sort comparator a no-op; throwing hands this
+            // candidate to the per-candidate fallback instead.
+            if (!Number.isFinite(score))
+                throw new Error('cross-encoder returned a non-finite score');
+            return score;
         };
-        return cachedPipeline;
     }
     catch {
         return null;
     }
 }
-/**
- * Track 2 reranker: MS-MARCO MiniLM cross-encoder.
- * Loads model on first call, then sub-100ms per query for top-K=50 candidates
- * on a typical developer laptop CPU. Falls back to identity ordering if the
- * model fails to load (no transformers, no network for first download, etc.).
- *
- * See docs/plans/2026-05-10-f6-reranker-hardening.md Task 6.
- */
+// One shared in-flight load: two first calls must not fetch the model twice.
+// A failed load clears the slot so a later call can try again.
+function loadPipeline() {
+    pipelineLoading ??= buildPipeline().then((pipe) => {
+        if (!pipe)
+            pipelineLoading = null;
+        return pipe;
+    });
+    return pipelineLoading;
+}
+/** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. */
 export const crossEncoderReranker = async (query, results, options) => {
     const topK = options?.topK ?? 50;
     const head = results.slice(0, topK);
     const pipe = await loadPipeline();
     if (!pipe) {
-        // Fallback: identity ordering with rerankScore = original score. Warn
-        // once per process so a silent identity-fallback doesn't mislead users
-        // into thinking the cross-encoder is doing work it isn't.
+        // Warn once per process: a silent identity fallback otherwise reads as a
+        // working reranker.
         if (!warnedOnFallback) {
             warnedOnFallback = true;
             // eslint-disable-next-line no-console
@@ -102,13 +115,10 @@ export const crossEncoderReranker = async (query, results, options) => {
     const scored = await Promise.all(head.map(async (r, i) => {
         let ceScore;
         try {
-            const out = await pipe(query, r.entry.content);
-            ceScore = Array.isArray(out) && out.length > 0 ? out[0].score : 0;
+            ceScore = await pipe(query, r.entry.content);
         }
         catch {
-            // Per-call inference failure (transient tensor error, bad input,
-            // etc.): fall back to original score for this candidate so a
-            // single bad inference doesn't sink the whole rerank pass.
+            // One bad inference must not sink the whole pass.
             ceScore = r.score;
         }
         return {
@@ -118,12 +128,8 @@ export const crossEncoderReranker = async (query, results, options) => {
             postRerankRank: 0,
         };
     }));
-    // T2 note: PLAIN stable score sort on purpose. The input `head` is already
-    // deterministically ordered (upstream content tail), so stability inherits
-    // that -- and when the cross-encoder produces tied scores (degenerate or
-    // no-signal cases), ties MUST fall back to the prior relevance order, not
-    // an arbitrary content order (the reranker-cross-encoder micro fixture
-    // fails otherwise: an all-tie rerank pass reordered its input).
+    // Plain stable sort on purpose: tied scores MUST fall back to the prior
+    // relevance order, never an arbitrary content order.
     scored.sort((a, b) => b.rerankScore - a.rerankScore);
     scored.forEach((r, i) => (r.postRerankRank = i + 1));
     return scored;

package/dist/src/rerankers/cross-encoder.js.map

@@ -1 +1 @@
-{"version":3,"file":"cross-encoder.js","sourceRoot":"","sources":["../../../src/rerankers/cross-encoder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cross-encoder.js","sourceRoot":"","sources":["../../../src/rerankers/cross-encoder.ts"],"names":[],"mappings":"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"}

package/dist/src/rerankers/index.js

@@ -1,7 +1,9 @@
 import { crossEncoderReranker } from './cross-encoder.js';
+import { jevReranker } from './jev.js';
 import { llmReranker } from './llm.js';
 const REGISTRY = {
     'cross-encoder': crossEncoderReranker,
+    jev: jevReranker,
     llm: llmReranker,
 };
 function isRegisteredRerankerName(name) {

package/dist/src/rerankers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rerankers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,MAAM,QAAQ,GAAG;IACf,eAAe,EAAE,oBAAoB;IACrC,GAAG,EAAE,WAAW;CACoB,CAAC;AAIvC,SAAS,wBAAwB,CAAC,IAAY;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAA+B;IACzD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,gBAAgB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rerankers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,MAAM,QAAQ,GAAG;IACf,eAAe,EAAE,oBAAoB;IACrC,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,WAAW;CACoB,CAAC;AAIvC,SAAS,wBAAwB,CAAC,IAAY;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAA+B;IACzD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,gBAAgB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}

package/dist/src/rerankers/jev.js

@@ -0,0 +1,116 @@
+import { crossEncoderReranker } from './cross-encoder.js';
+const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
+const DEFAULT_TIMEOUT_MS = 5_000;
+const TRUNCATE_CHARS = 1200;
+// The pool size every number in docs/evals/2026-09-19-jev-reranker.md was measured at.
+export const JEV_DEFAULT_TOP_K = 40;
+function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n)}...`;
+}
+// Number.isFinite rejects a string or null without coercing it, which the
+// declared type cannot promise about a third-party payload.
+function isProbability(v) {
+    return v !== undefined && Number.isFinite(v) && v >= 0 && v <= 1;
+}
+// A half-scored list ranks worse than the order it would replace, so one bad
+// answer voids the whole response.
+function parseScores(answers, n) {
+    const out = [];
+    for (let i = 1; i <= n; i++) {
+        const v = answers?.[`c${i}`]?.noul;
+        if (!isProbability(v))
+            return null;
+        out.push(v);
+    }
+    return out;
+}
+/** One batched request for the whole candidate list. Rejects with the reason when there are no usable scores. */
+async function requestScores(query, head) {
+    const key = process.env.TYPESAFE_API_KEY;
+    if (!key)
+        throw new Error('TYPESAFE_API_KEY not set');
+    const lines = head.map((r, i) => `[${i + 1}] ${truncate(r.entry.content, TRUNCATE_CHARS)}`);
+    const state = `Query: ${query}\n\nNumbered candidate memories from an AI coding agent's project store:\n\n${lines.join('\n\n')}`;
+    const questions = {};
+    for (let i = 1; i <= head.length; i++) {
+        questions[`c${i}`] = {
+            type: 'noul',
+            instructions: `Probability that candidate ${i} (numbered in the state above) helps answer the query.`,
+        };
+    }
+    const parsed = Number.parseInt(process.env.HIPPO_JEV_TIMEOUT_MS ?? '', 10);
+    const timeoutMs = parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const resp = await fetch(ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+            body: JSON.stringify({
+                state,
+                model: process.env.HIPPO_JEV_MODEL ?? 'jev-latest',
+                questions,
+            }),
+            signal: controller.signal,
+        });
+        if (!resp.ok) {
+            // A third-party header ends up on stderr, so keep printable ASCII only.
+            const requestId = resp.headers.get('x-request-id')?.replace(/[^\x20-\x7e]/g, '').slice(0, 64);
+            await resp.body?.cancel();
+            throw new Error(`HTTP ${resp.status}${requestId ? `, request ${requestId}` : ''}`);
+        }
+        const body = await resp.json();
+        const scores = parseScores(body.answers, head.length);
+        if (!scores)
+            throw new Error('incomplete or out-of-range answers');
+        return scores;
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new Error(`no answer within ${timeoutMs} ms`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Builds a Jev reranker around the reranker it degrades to. Exported so a test can pass a stand-in. */
+export function createJevReranker(localFallback) {
+    let warned = false;
+    return async (query, results, options) => {
+        const head = results.slice(0, options?.topK ?? JEV_DEFAULT_TOP_K);
+        if (head.length === 0)
+            return [];
+        let scores;
+        try {
+            scores = await requestScores(query, head);
+        }
+        catch (err) {
+            // A read path never throws, and never hands back the unranked order
+            // without saying so: warn once, then use the free local reranker.
+            if (!warned) {
+                warned = true;
+                const reason = err instanceof Error ? err.message : 'unknown error';
+                // eslint-disable-next-line no-console
+                console.warn(`[hippo] jev reranker unavailable (${reason}); falling back to the local cross-encoder. Subsequent calls will not repeat this warning.`);
+            }
+            return localFallback(query, head, options);
+        }
+        const scored = head.map((r, i) => ({
+            ...r,
+            rerankScore: scores[i],
+            preRerankRank: r.preRerankRank ?? i + 1,
+            postRerankRank: 0,
+        }));
+        // Stable sort: ties fall back to the prior relevance order.
+        scored.sort((a, b) => b.rerankScore - a.rerankScore);
+        scored.forEach((r, i) => (r.postRerankRank = i + 1));
+        return scored;
+    };
+}
+/** Track 4 reranker: hosted TypeSafe Jev, opt-in and paid (TYPESAFE_API_KEY), one batched call per recall.
+ *  Any failure warns once and delegates to the local cross-encoder. Scores are not bit-stable run to run.
+ *  Cost, env vars, evidence and limits: docs/evals/2026-09-19-jev-reranker.md. */
+export const jevReranker = createJevReranker(crossEncoderReranker);
+//# sourceMappingURL=jev.js.map

package/dist/src/rerankers/jev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jev.js","sourceRoot":"","sources":["../../../src/rerankers/jev.ts"],"names":[],"mappings":"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"}

package/dist/src/store.js

@@ -10,7 +10,7 @@ import { Layer, generateId } from './memory.js';
 import { dumpFrontmatter, parseFrontmatter } from './yaml.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta, isFtsAvailable, pruneConsolidationRuns, getHippoDbPath, } from './db.js';
 import { rowToSessionHandoff, isHandoffOutcome } from './handoff.js';
-import { CARD_TRANSITIONS } from './card.js';
+import { CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
 import { tokenize } from './search.js';
 import { appendAuditEvent } from './audit.js';
 import { resolveTenantId } from './tenant.js';
@@ -2868,6 +2868,29 @@ function insertCardComment(db, tenantId, cardId, author, body) {
     const id = Number(result.lastInsertRowid ?? 0);
     return { id, cardId, author, body, createdAt: now };
 }
+function leaseUntilFrom(now) {
+    return new Date(Date.parse(now) + CARD_LEASE_MS).toISOString();
+}
+function assertRunId(runId) {
+    if (!Number.isSafeInteger(runId) || runId <= 0) {
+        throw new Error(`Invalid run id: ${runId} (expected a positive integer)`);
+    }
+}
+// A second run that has not ended means a corrupt store; throw rather than guess which run the caller means.
+function isLiveRun(db, tenantId, cardId, runId) {
+    // SAFETY: rows' shape matches the single `id` column named in the SELECT below.
+    const rows = db.prepare(`SELECT id FROM card_runs WHERE tenant_id = ? AND card = ? AND ended IS NULL`).all(tenantId, cardId);
+    if (rows.length > 1) {
+        throw new Error(`card ${cardId} has ${rows.length} runs that have not ended`);
+    }
+    return rows[0]?.id === runId;
+}
+function closeLiveRun(db, tenantId, cardId, outcome, now) {
+    db.prepare(`
+    UPDATE card_runs SET ended = ?, outcome = ?, updated_at = ?
+    WHERE card = ? AND tenant_id = ? AND ended IS NULL
+  `).run(now, outcome, now, cardId, tenantId);
+}
 // The single status-mutating seam (rule 15): CARD_TRANSITIONS is the one
 // runtime authority, so a hand-copied wrong `from` list fails fast here.
 export function transitionCard(db, tenantId, cardId, from, to, extra) {
@@ -2877,12 +2900,14 @@ export function transitionCard(db, tenantId, cardId, from, to, extra) {
         }
     }
     const now = new Date().toISOString();
+    // Lease columns follow status: set on the move to running, cleared on every other move (rule 15).
+    const lease = to === 'running' ? [leaseUntilFrom(now), now] : [null, null];
     const fromPlaceholders = from.map(() => '?').join(', ');
     const sql = `
-    UPDATE cards SET status = ?, updated_at = ?${extra?.setSql ? `, ${extra.setSql}` : ''}
+    UPDATE cards SET status = ?, updated_at = ?, lease_until = ?, heartbeat_at = ?${extra?.setSql ? `, ${extra.setSql}` : ''}
     WHERE id = ? AND tenant_id = ? AND status IN (${fromPlaceholders})${extra?.whereSql ? ` AND ${extra.whereSql}` : ''}
   `;
-    const params = [to, now, ...(extra?.params ?? []), cardId, tenantId, ...from];
+    const params = [to, now, ...lease, ...(extra?.params ?? []), cardId, tenantId, ...from];
     const result = db.prepare(sql).run(...params);
     return Number(result.changes ?? 0);
 }
@@ -3046,7 +3071,7 @@ export function loadLatestHandoffForCard(hippoRoot, tenantId, cardId) {
         closeHippoDb(db);
     }
 }
-/** Atomic claim: WHERE status IN (ready, blocked) AND assignee_runtime IS NULL decides the race. Throws on an unknown card id; returns null for a card not ready/blocked or already claimed. */
+/** Atomic claim: WHERE status IN (ready, blocked) AND assignee_runtime IS NULL decides the race. Throws on an unknown card id; returns null for a card not ready/blocked or already claimed. Sets a CARD_LEASE_MS lease and returns the new run's id as runId. */
 export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
     assertTenantId('claimCard', tenantId);
     if (runtime.trim() === '') {
@@ -3056,6 +3081,7 @@ export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
     const db = openHippoDb(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
+        let runId = 0;
         try {
             const changes = transitionCard(db, tenantId, id, ['ready', 'blocked'], 'running', {
                 setSql: 'assignee_runtime = ?',
@@ -3070,10 +3096,46 @@ export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
                 return null;
             }
             const now = new Date().toISOString();
-            db.prepare(`
+            const insert = db.prepare(`
         INSERT INTO card_runs (card, runtime, session_id, started, created_at, updated_at, tenant_id)
         VALUES (?, ?, ?, ?, ?, ?, ?)
       `).run(id, runtime, sessionId ?? null, now, now, now, tenantId);
+            runId = Number(insert.lastInsertRowid ?? 0);
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* commit may have already rolled back */ }
+            throw error;
+        }
+        return { ...loadCardRow(db, tenantId, id), runId };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Moves a running card's lease to CARD_LEASE_MS from now and records the heartbeat; updated_at is left alone. Throws on an unknown card id or a run id that is not a positive integer; returns null unless the card is running and runId is its live run. */
+export function heartbeatCard(hippoRoot, tenantId, id, runId) {
+    assertTenantId('heartbeatCard', tenantId);
+    assertRunId(runId);
+    initStore(hippoRoot);
+    const db = openHippoDb(hippoRoot);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const card = loadCardRow(db, tenantId, id);
+            if (!card) {
+                throw new Error(`unknown card id: ${id}`);
+            }
+            if (card.status !== 'running' || !isLiveRun(db, tenantId, id, runId)) {
+                db.exec('ROLLBACK');
+                return null;
+            }
+            const now = new Date().toISOString();
+            db.prepare(`UPDATE cards SET lease_until = ?, heartbeat_at = ? WHERE id = ? AND tenant_id = ?`)
+                .run(leaseUntilFrom(now), now, id, tenantId);
             db.exec('COMMIT');
         }
         catch (error) {
@@ -3089,18 +3151,21 @@ export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
         closeHippoDb(db);
     }
 }
-/** Requires the card be running; closes the live run as blocked and files reason as a comment. Throws on an unknown card id; returns null for a card not running. */
-export function blockCard(hippoRoot, tenantId, id, reason) {
+/** Requires the card be running; closes the live run as blocked and files reason as a comment. Throws on an unknown card id; returns null for a card not running. When runId is given, returns null unless it is the card's live run. */
+export function blockCard(hippoRoot, tenantId, id, reason, runId) {
     assertTenantId('blockCard', tenantId);
     if (reason.trim() === '') {
         throw new Error('reason must not be empty');
     }
+    if (runId !== undefined)
+        assertRunId(runId);
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
-            const changes = transitionCard(db, tenantId, id, ['running'], 'blocked', { setSql: 'assignee_runtime = NULL' });
+            const allowed = runId === undefined || isLiveRun(db, tenantId, id, runId);
+            const changes = allowed ? transitionCard(db, tenantId, id, ['running'], 'blocked', { setSql: 'assignee_runtime = NULL' }) : 0;
             if (changes === 0) {
                 if (!loadCardRow(db, tenantId, id)) {
                     throw new Error(`unknown card id: ${id}`);
@@ -3110,10 +3175,7 @@ export function blockCard(hippoRoot, tenantId, id, reason) {
             }
             const now = new Date().toISOString();
             // Close the interrupted run here so completeCard's ended IS NULL scope only ever matches the live run.
-            db.prepare(`
-        UPDATE card_runs SET ended = ?, outcome = 'blocked', updated_at = ?
-        WHERE card = ? AND tenant_id = ? AND ended IS NULL
-      `).run(now, now, id, tenantId);
+            closeLiveRun(db, tenantId, id, 'blocked', now);
             insertCardComment(db, tenantId, id, 'system', reason);
             db.exec('COMMIT');
         }
@@ -3130,15 +3192,18 @@ export function blockCard(hippoRoot, tenantId, id, reason) {
         closeHippoDb(db);
     }
 }
-/** Requires the card be running; moves it to review with no other side effects. Throws on an unknown card id; returns null for a card not running. */
-export function reviewCard(hippoRoot, tenantId, id) {
+/** Requires the card be running; moves it to review, clearing its lease and heartbeat and keeping its live run. When runId is given, returns null unless it is the card's live run. Throws on an unknown card id; returns null for a card not running. */
+export function reviewCard(hippoRoot, tenantId, id, runId) {
     assertTenantId('reviewCard', tenantId);
+    if (runId !== undefined)
+        assertRunId(runId);
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
-            const changes = transitionCard(db, tenantId, id, ['running'], 'review');
+            const allowed = runId === undefined || isLiveRun(db, tenantId, id, runId);
+            const changes = allowed ? transitionCard(db, tenantId, id, ['running'], 'review') : 0;
             if (changes === 0) {
                 if (!loadCardRow(db, tenantId, id)) {
                     throw new Error(`unknown card id: ${id}`);
@@ -3161,12 +3226,14 @@ export function reviewCard(hippoRoot, tenantId, id) {
         closeHippoDb(db);
     }
 }
-/** Requires the card be in review; closes the live run with outcome. Outcome 'success' moves the card to done and, in the same transaction, promotes any child whose parents are now all done; 'failure' or 'partial' moves it to shelved and promotes nothing. Throws on an unknown card id; returns null for a card not in review. */
-export function completeCard(hippoRoot, tenantId, id, outcome) {
+/** Requires the card be in review; closes the live run with outcome. Outcome 'success' moves the card to done and, in the same transaction, promotes any child whose parents are now all done; 'failure' or 'partial' moves it to shelved and promotes nothing. Throws on an unknown card id; returns null for a card not in review. When runId is given, returns null unless it is the card's live run. */
+export function completeCard(hippoRoot, tenantId, id, outcome, runId) {
     assertTenantId('completeCard', tenantId);
     if (!isHandoffOutcome(outcome)) {
         throw new Error(`invalid card outcome: ${String(outcome)}`);
     }
+    if (runId !== undefined)
+        assertRunId(runId);
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
@@ -3174,7 +3241,8 @@ export function completeCard(hippoRoot, tenantId, id, outcome) {
         let promotedChildren = [];
         try {
             const target = outcome === 'success' ? 'done' : 'shelved';
-            const changes = transitionCard(db, tenantId, id, ['review'], target);
+            const allowed = runId === undefined || isLiveRun(db, tenantId, id, runId);
+            const changes = allowed ? transitionCard(db, tenantId, id, ['review'], target) : 0;
             if (changes === 0) {
                 if (!loadCardRow(db, tenantId, id)) {
                     throw new Error(`unknown card id: ${id}`);
@@ -3183,10 +3251,7 @@ export function completeCard(hippoRoot, tenantId, id, outcome) {
                 return null;
             }
             const now = new Date().toISOString();
-            db.prepare(`
-        UPDATE card_runs SET ended = ?, outcome = ?, updated_at = ?
-        WHERE card = ? AND tenant_id = ? AND ended IS NULL
-      `).run(now, outcome, now, id, tenantId);
+            closeLiveRun(db, tenantId, id, outcome, now);
             // Not best-effort (rule 12): promotion runs in this same transaction, so a
             // card can never be `done` with an un-evaluated child.
             if (target === 'done') {
@@ -3223,6 +3288,41 @@ export function completeCard(hippoRoot, tenantId, id, outcome) {
         closeHippoDb(db);
     }
 }
+/** Returns to ready every running card of the tenant whose lease has expired or is missing: clears its assignee, closes its live run as 'reclaimed' and leaves its handoffs alone, all in one write transaction. Returns the reclaimed card ids in id order. */
+export function reclaimExpiredCards(hippoRoot, tenantId) {
+    assertTenantId('reclaimExpiredCards', tenantId);
+    initStore(hippoRoot);
+    const db = openHippoDb(hippoRoot);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            // Read lease times under the write lock, so a heartbeat that committed while we waited wins.
+            const now = new Date().toISOString();
+            // SAFETY: rows' shape matches the single `id` column named in the SELECT below.
+            const ids = db.prepare(`
+        SELECT id FROM cards
+        WHERE tenant_id = ? AND status = 'running' AND (lease_until IS NULL OR lease_until < ?)
+        ORDER BY id
+      `).all(tenantId, now).map((r) => r.id);
+            for (const id of ids) {
+                transitionCard(db, tenantId, id, ['running'], 'ready', { setSql: 'assignee_runtime = NULL' });
+                closeLiveRun(db, tenantId, id, 'reclaimed', now);
+            }
+            db.exec('COMMIT');
+            return ids;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* commit may have already rolled back */ }
+            throw error;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /** Appends a comment to cardId in any card status; throws if cardId is not a card of this tenant. */
 export function addCardComment(hippoRoot, tenantId, cardId, author, body) {
     assertTenantId('addCardComment', tenantId);