@psiclawops/hypermem 0.6.2 → 0.8.0

package/dist/message-store.js

@@ -5,7 +5,7 @@
  * All messages are stored in provider-neutral format.
  * This is the write-through layer: Redis → here.
  */
-import { getOrCreateActiveContext, updateContextHead } from './context-store.js';
+import { getOrCreateActiveContext, updateContextHead, getArchivedContext } from './context-store.js';
 function nowIso() {
     return new Date().toISOString();
 }
@@ -332,6 +332,12 @@ export class MessageStore {
      *
      * Falls back to getRecentMessages if the head message has no parent chain
      * (e.g., legacy data before backfill).
+     *
+     * @boundary SHARED DAG PRIMITIVE — not for direct call at mining call sites.
+     * @policy See specs/DAG_HELPER_POLICY.md for operator-boundary rules.
+     * Use mineArchivedContext / mineArchivedContexts for archived context mining,
+     * and the active-composition paths for live session history. Direct call sites
+     * outside this class should be limited to exceptional diagnostic use.
      */
     getHistoryByDAGWalk(headMessageId, limit = 50) {
         try {
@@ -414,6 +420,136 @@ export class MessageStore {
             .get(conversationId);
         return row.count;
     }
+    /**
+     * Get the full message chain for an archived or forked context.
+     *
+     * Throws if the context does not exist or is active (not archived/forked).
+     * Returns an empty array if the context has no head message.
+     * Delegates to getHistoryByDAGWalk for the actual chain retrieval.
+     */
+    getArchivedChain(contextId, limit) {
+        const context = getArchivedContext(this.db, contextId);
+        if (!context) {
+            throw new Error('getArchivedChain: context must be archived or forked');
+        }
+        if (context.headMessageId === null) {
+            return [];
+        }
+        return this.getHistoryByDAGWalk(context.headMessageId, limit ?? 200);
+    }
+    // ─── Archived Mining (Phase 4 Sprint 2 / Sprint 3) ─────────────
+    /**
+     * Default maximum number of contextIds accepted by mineArchivedContexts.
+     * Callers may supply a lower value but not a higher one.
+     */
+    static ARCHIVED_MULTI_CONTEXT_DEFAULT_MAX = 20;
+    /**
+     * Hard ceiling for mineArchivedContexts.
+     * Values above this are clamped to this number regardless of caller intent.
+     * This prevents unbounded DB fan-out on misconfigured or adversarial inputs.
+     */
+    static ARCHIVED_MULTI_CONTEXT_HARD_CEILING = 50;
+    // ─── Archived Mining (Phase 4 Sprint 2) ───────────────────────
+    /**
+     * Mine messages from a single archived or forked context.
+     *
+     * - Rejects active or missing contexts with a clear error.
+     * - Hard-caps limit at 200.
+     * - Defaults excludeHeartbeats to true.
+     * - Optionally filters by ftsQuery (client-side substring match for Sprint 3; SQL FTS is deferred).
+     * - Routes through getHistoryByDAGWalk for DAG-native retrieval.
+     * - Returns ArchivedMiningResult<StoredMessage[]> with isHistorical: true.
+     *
+     * This method does NOT widen active composition — it only operates on
+     * explicitly non-active (archived/forked) contexts.
+     */
+    mineArchivedContext(query) {
+        const { contextId, limit, excludeHeartbeats = true, ftsQuery } = query;
+        const context = getArchivedContext(this.db, contextId);
+        if (!context) {
+            throw new Error(`mineArchivedContext: context ${contextId} does not exist or is not archived/forked. ` +
+                `Only archived or forked contexts may be mined.`);
+        }
+        // Hard cap at 200
+        const effectiveLimit = Math.min(limit ?? 200, 200);
+        let messages = [];
+        if (context.headMessageId !== null) {
+            messages = this.getHistoryByDAGWalk(context.headMessageId, effectiveLimit);
+        }
+        // Apply heartbeat filter (default: exclude)
+        if (excludeHeartbeats) {
+            messages = messages.filter(m => !m.isHeartbeat);
+        }
+        // Client-side ftsQuery filter (substring match for Sprint 2)
+        if (ftsQuery && ftsQuery.trim().length > 0) {
+            const q = ftsQuery.trim().toLowerCase();
+            messages = messages.filter(m => (m.textContent ?? '').toLowerCase().includes(q));
+        }
+        return {
+            isHistorical: true,
+            contextId: context.id,
+            agentId: context.agentId,
+            sessionKey: context.sessionKey,
+            contextStatus: context.status,
+            contextUpdatedAt: context.updatedAt,
+            data: messages,
+        };
+    }
+    /**
+     * Mine messages from multiple archived or forked contexts.
+     *
+     * ## maxContexts gate (Phase 4 Sprint 3, Task 1)
+     * Accepts an optional `maxContexts` in opts to control how many contextIds
+     * are accepted in a single call:
+     * - Default: ARCHIVED_MULTI_CONTEXT_DEFAULT_MAX (20).
+     * - Hard ceiling: ARCHIVED_MULTI_CONTEXT_HARD_CEILING (50).
+     * - A caller-supplied value above the hard ceiling is clamped to the ceiling
+     *   (not rejected), so callers need not know the exact constant.
+     * - A caller-supplied value at or below the ceiling is used as-is.
+     * - If contextIds.length exceeds the effective max, this method THROWS
+     *   immediately — it does NOT soft-skip or truncate.
+     *
+     * ## Other behaviors (unchanged from Sprint 2)
+     * - Soft-skips active or missing contextIds with a warning (does not throw).
+     * - Preserves input order in the result array.
+     * - Applies per-context limit and same filters as mineArchivedContext.
+     * - Returns one ArchivedMiningResult per valid archived context.
+     *
+     * This method does NOT widen active composition — it only operates on
+     * explicitly non-active (archived/forked) contexts.
+     */
+    mineArchivedContexts(contextIds, opts) {
+        // ── maxContexts gate ──────────────────────────────────────────────────
+        const { maxContexts: callerMax, ...perContextOpts } = opts ?? {};
+        const effectiveMax = callerMax !== undefined
+            ? Math.min(callerMax, MessageStore.ARCHIVED_MULTI_CONTEXT_HARD_CEILING)
+            : MessageStore.ARCHIVED_MULTI_CONTEXT_DEFAULT_MAX;
+        if (contextIds.length > effectiveMax) {
+            throw new Error(`mineArchivedContexts: too many contextIds (${contextIds.length}). ` +
+                `Effective limit is ${effectiveMax} ` +
+                `(hard ceiling: ${MessageStore.ARCHIVED_MULTI_CONTEXT_HARD_CEILING}, ` +
+                `default: ${MessageStore.ARCHIVED_MULTI_CONTEXT_DEFAULT_MAX}). ` +
+                `Pass fewer contextIds or supply a higher maxContexts (max: ${MessageStore.ARCHIVED_MULTI_CONTEXT_HARD_CEILING}).`);
+        }
+        // ── end gate ─────────────────────────────────────────────────────────
+        const results = [];
+        for (const contextId of contextIds) {
+            const context = getArchivedContext(this.db, contextId);
+            if (!context) {
+                console.warn(`[hypermem:message-store] mineArchivedContexts: skipping contextId ${contextId} ` +
+                    `— does not exist or is not archived/forked (may be active or missing).`);
+                continue;
+            }
+            try {
+                results.push(this.mineArchivedContext({ contextId, ...perContextOpts }));
+            }
+            catch (err) {
+                console.warn(`[hypermem:message-store] mineArchivedContexts: skipping contextId ${contextId} ` +
+                    `— ${err.message}`);
+            }
+        }
+        return results;
+    }
     // ─── Helpers ─────────────────────────────────────────────────
     /**
      * Infer channel type from session key format.

package/dist/proactive-pass.d.ts

@@ -42,7 +42,7 @@ export interface ToolDecayResult {
  * Deletions are wrapped in a single transaction. The FTS5 trigger handles
  * index cleanup automatically (msg_fts_ad fires on DELETE).
  */
-export declare function runNoiseSweep(db: DatabaseSync, conversationId: number, recentWindowSize?: number): NoiseSweepResult;
+export declare function runNoiseSweep(db: DatabaseSync, conversationId: number, recentWindowSize?: number, maxCandidates?: number): NoiseSweepResult;
 /**
  * Truncate oversized tool_results outside the recent window.
  *
@@ -59,5 +59,5 @@ export declare function runNoiseSweep(db: DatabaseSync, conversationId: number,
  *
  * Mutations are committed in a single transaction.
  */
-export declare function runToolDecay(db: DatabaseSync, conversationId: number, recentWindowSize?: number): ToolDecayResult;
+export declare function runToolDecay(db: DatabaseSync, conversationId: number, recentWindowSize?: number, maxCandidates?: number): ToolDecayResult;
 //# sourceMappingURL=proactive-pass.d.ts.map

package/dist/proactive-pass.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proactive-pass.d.ts","sourceRoot":"","sources":["../src/proactive-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AA6CD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,gBAAgB,GAAE,MAAW,GAC5B,gBAAgB,CA2ElB;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,gBAAgB,GAAE,MAAW,GAC5B,eAAe,CAiGjB"}
+{"version":3,"file":"proactive-pass.d.ts","sourceRoot":"","sources":["../src/proactive-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAwFD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,gBAAgB,GAAE,MAAW,EAC7B,aAAa,GAAE,MAAiB,GAC/B,gBAAgB,CAwFlB;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,gBAAgB,GAAE,MAAW,EAC7B,aAAa,GAAE,MAAiB,GAC/B,eAAe,CAgHjB"}

package/dist/proactive-pass.js

@@ -44,6 +44,44 @@ function getMaxMessageIndex(db, conversationId) {
         .get(conversationId);
     return typeof row.max_index === 'number' ? row.max_index : -1;
 }
+/**
+ * Filter candidate message ids down to rows that are safe to delete without
+ * violating HyperMem's FK edges.
+ *
+ * Current blockers:
+ *   - summary_messages.message_id -> messages.id
+ *   - messages.parent_id -> messages.id (child rows point at parent rows)
+ */
+function getDeletableMessageIds(db, candidateIds) {
+    if (candidateIds.length === 0)
+        return { deletableIds: [], blockedIds: [] };
+    const placeholders = candidateIds.map(() => '?').join(', ');
+    const blocked = db
+        .prepare(`
+      SELECT DISTINCT id
+      FROM (
+        SELECT sm.message_id AS id
+        FROM summary_messages sm
+        WHERE sm.message_id IN (${placeholders})
+
+        UNION
+
+        SELECT parent.id AS id
+        FROM messages child
+        JOIN messages parent ON parent.id = child.parent_id
+        WHERE child.parent_id IN (${placeholders})
+      ) blocked
+    `)
+        .all(...candidateIds, ...candidateIds);
+    if (blocked.length === 0)
+        return { deletableIds: candidateIds, blockedIds: [] };
+    const blockedIds = blocked.map(row => row.id);
+    const blockedSet = new Set(blockedIds);
+    return {
+        deletableIds: candidateIds.filter(id => !blockedSet.has(id)),
+        blockedIds,
+    };
+}
 /**
  * Decide if a message is noise based on content + is_heartbeat flag.
  *
@@ -73,7 +111,7 @@ function isNoiseMessage(textContent, isHeartbeat) {
  * Deletions are wrapped in a single transaction. The FTS5 trigger handles
  * index cleanup automatically (msg_fts_ad fires on DELETE).
  */
-export function runNoiseSweep(db, conversationId, recentWindowSize = 20) {
+export function runNoiseSweep(db, conversationId, recentWindowSize = 20, maxCandidates = Infinity) {
     const ZERO = { messagesDeleted: 0, passType: 'noise_sweep' };
     try {
         const safeWindow = resolveSafeWindow(recentWindowSize);
@@ -101,11 +139,16 @@ export function runNoiseSweep(db, conversationId, recentWindowSize = 20) {
             .all(conversationId, cutoff);
         if (candidates.length === 0)
             return ZERO;
-        // Filter to noise messages
-        const toDelete = candidates.filter(row => isNoiseMessage(row.text_content, row.is_heartbeat));
-        if (toDelete.length === 0)
+        // Filter to noise messages, respecting per-pass candidate cap
+        const toDelete = candidates.filter(row => isNoiseMessage(row.text_content, row.is_heartbeat)).slice(0, Number.isFinite(maxCandidates) ? maxCandidates : undefined);
+        if (toDelete.length === 0) {
             return ZERO;
-        const ids = toDelete.map(r => r.id);
+        }
+        const candidateIds = toDelete.map(r => r.id);
+        const { deletableIds: ids, blockedIds } = getDeletableMessageIds(db, candidateIds);
+        if (ids.length === 0) {
+            return ZERO;
+        }
         // Delete in a transaction; use chunked IN clauses to avoid
         // SQLite's SQLITE_LIMIT_VARIABLE_NUMBER (default 999).
         let totalDeleted = 0;
@@ -126,6 +169,9 @@ export function runNoiseSweep(db, conversationId, recentWindowSize = 20) {
             db.prepare('ROLLBACK').run();
             throw innerErr;
         }
+        if (totalDeleted > 0) {
+            console.log(`[proactive-pass] Noise sweep conversation=${conversationId} candidates=${candidates.length} noise=${candidateIds.length} deleted=${totalDeleted} skippedReferenced=${blockedIds.length} cutoff=${cutoff}`);
+        }
         return { messagesDeleted: totalDeleted, passType: 'noise_sweep' };
     }
     catch (err) {
@@ -150,16 +196,18 @@ export function runNoiseSweep(db, conversationId, recentWindowSize = 20) {
  *
  * Mutations are committed in a single transaction.
  */
-export function runToolDecay(db, conversationId, recentWindowSize = 40) {
+export function runToolDecay(db, conversationId, recentWindowSize = 40, maxCandidates = Infinity) {
     const ZERO = { messagesUpdated: 0, bytesFreed: 0, passType: 'tool_decay' };
     try {
         const safeWindow = resolveSafeWindow(recentWindowSize);
         const maxIndex = getMaxMessageIndex(db, conversationId);
-        if (maxIndex < 0)
+        if (maxIndex < 0) {
             return ZERO;
+        }
         const cutoff = maxIndex - safeWindow;
-        if (cutoff <= 0)
+        if (cutoff <= 0) {
             return ZERO;
+        }
         // Fetch messages with large tool_results outside the recent window.
         const candidates = db
             .prepare(`
@@ -171,11 +219,13 @@ export function runToolDecay(db, conversationId, recentWindowSize = 40) {
           AND length(tool_results) > 2000
       `)
             .all(conversationId, cutoff);
-        if (candidates.length === 0)
+        if (candidates.length === 0) {
             return ZERO;
-        // Build the update list by processing each candidate.
+        }
+        // Build the update list by processing each candidate, respecting per-pass cap.
+        const cappedCandidates = Number.isFinite(maxCandidates) ? candidates.slice(0, maxCandidates) : candidates;
         const updates = [];
-        for (const row of candidates) {
+        for (const row of cappedCandidates) {
             let parsed;
             try {
                 parsed = JSON.parse(row.tool_results);
@@ -207,8 +257,9 @@ export function runToolDecay(db, conversationId, recentWindowSize = 40) {
                 updates.push({ id: row.id, newJson, savedBytes });
             }
         }
-        if (updates.length === 0)
+        if (updates.length === 0) {
             return ZERO;
+        }
         let totalUpdated = 0;
         let totalBytesFreed = 0;
         db.prepare('BEGIN').run();
@@ -225,6 +276,9 @@ export function runToolDecay(db, conversationId, recentWindowSize = 40) {
             db.prepare('ROLLBACK').run();
             throw innerErr;
         }
+        if (totalUpdated > 0) {
+            console.log(`[proactive-pass] Tool decay conversation=${conversationId} candidates=${candidates.length} updated=${totalUpdated} bytesFreed=${totalBytesFreed} cutoff=${cutoff}`);
+        }
         return {
             messagesUpdated: totalUpdated,
             bytesFreed: totalBytesFreed,

package/dist/replay-recovery.d.ts

@@ -0,0 +1,29 @@
+import { type ReplayMarker, type ReplayState } from './degradation.js';
+export interface ReplayRecoveryInputs {
+    currentState?: ReplayState | '' | null;
+    runtimeTokens: number;
+    redisTokens: number;
+    effectiveBudget: number;
+}
+export interface ReplayRecoveryDecision {
+    active: boolean;
+    shouldSkipCacheReplay: boolean;
+    trimTargetOverride?: number;
+    historyDepthCap?: number;
+    emittedMarker?: ReplayMarker;
+    emittedText?: string;
+    nextState: ReplayState | null;
+}
+export declare const REPLAY_RECOVERY_POLICY: {
+    readonly enterPressure: 0.8;
+    readonly exitPressure: 0.65;
+    readonly redisColdFraction: 0.2;
+    readonly enterTrimTarget: 0.2;
+    readonly stabilizingTrimTarget: 0.35;
+    readonly historyDepthCap: 60;
+    readonly redisFloorTokens: 500;
+};
+export declare function isColdRedisReplay(inputs: ReplayRecoveryInputs): boolean;
+export declare function isReplayRecovered(inputs: ReplayRecoveryInputs): boolean;
+export declare function decideReplayRecovery(inputs: ReplayRecoveryInputs): ReplayRecoveryDecision;
+//# sourceMappingURL=replay-recovery.d.ts.map

package/dist/replay-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-recovery.d.ts","sourceRoot":"","sources":["../src/replay-recovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,WAAW,GAAG,EAAE,GAAG,IAAI,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/B;AAED,eAAO,MAAM,sBAAsB;;;;;;;;CAQzB,CAAC;AAgBX,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAKvE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAKvE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,CA+DzF"}

package/dist/replay-recovery.js

@@ -0,0 +1,82 @@
+import { formatReplayMarker, } from './degradation.js';
+export const REPLAY_RECOVERY_POLICY = {
+    enterPressure: 0.80,
+    exitPressure: 0.65,
+    redisColdFraction: 0.20,
+    enterTrimTarget: 0.20,
+    stabilizingTrimTarget: 0.35,
+    historyDepthCap: 60,
+    redisFloorTokens: 500,
+};
+function coldRedisThreshold(runtimeTokens) {
+    return Math.max(REPLAY_RECOVERY_POLICY.redisFloorTokens, Math.floor(runtimeTokens * REPLAY_RECOVERY_POLICY.redisColdFraction));
+}
+function recoveredRedisThreshold(effectiveBudget) {
+    return Math.max(REPLAY_RECOVERY_POLICY.redisFloorTokens, Math.floor(effectiveBudget * REPLAY_RECOVERY_POLICY.redisColdFraction));
+}
+export function isColdRedisReplay(inputs) {
+    return (inputs.runtimeTokens > inputs.effectiveBudget * REPLAY_RECOVERY_POLICY.enterPressure &&
+        inputs.redisTokens < coldRedisThreshold(inputs.runtimeTokens));
+}
+export function isReplayRecovered(inputs) {
+    return (inputs.runtimeTokens <= inputs.effectiveBudget * REPLAY_RECOVERY_POLICY.exitPressure &&
+        inputs.redisTokens >= recoveredRedisThreshold(inputs.effectiveBudget));
+}
+export function decideReplayRecovery(inputs) {
+    const currentState = inputs.currentState ?? null;
+    if (!currentState) {
+        if (!isColdRedisReplay(inputs)) {
+            return {
+                active: false,
+                shouldSkipCacheReplay: false,
+                nextState: null,
+            };
+        }
+        const emittedMarker = {
+            state: 'entering',
+            status: 'bounded',
+            reason: 'replay_cold_redis',
+            summary: 'cold restart, keep the window bounded',
+        };
+        return {
+            active: true,
+            shouldSkipCacheReplay: true,
+            trimTargetOverride: REPLAY_RECOVERY_POLICY.enterTrimTarget,
+            historyDepthCap: REPLAY_RECOVERY_POLICY.historyDepthCap,
+            emittedMarker,
+            emittedText: formatReplayMarker(emittedMarker),
+            nextState: 'stabilizing',
+        };
+    }
+    if (isReplayRecovered(inputs)) {
+        const emittedMarker = {
+            state: 'exited',
+            status: 'bounded',
+            reason: 'replay_exited',
+            summary: 'stable window restored',
+        };
+        return {
+            active: false,
+            shouldSkipCacheReplay: false,
+            emittedMarker,
+            emittedText: formatReplayMarker(emittedMarker),
+            nextState: null,
+        };
+    }
+    const emittedMarker = {
+        state: 'stabilizing',
+        status: 'bounded',
+        reason: 'replay_stabilizing',
+        summary: 'replay window stabilizing, keep it bounded',
+    };
+    return {
+        active: true,
+        shouldSkipCacheReplay: true,
+        trimTargetOverride: REPLAY_RECOVERY_POLICY.stabilizingTrimTarget,
+        historyDepthCap: REPLAY_RECOVERY_POLICY.historyDepthCap,
+        emittedMarker,
+        emittedText: formatReplayMarker(emittedMarker),
+        nextState: 'stabilizing',
+    };
+}
+//# sourceMappingURL=replay-recovery.js.map

package/dist/reranker.d.ts

@@ -0,0 +1,95 @@
+/**
+ * hypermem Reranker
+ *
+ * Pluggable reranking interface with circuit-breaker protection and graceful
+ * degradation. Callers that receive null fall back to the original document
+ * order without disruption.
+ *
+ * Providers:
+ *   - ZeroEntropyReranker — https://api.zeroentropy.dev/v1/rerank (zerank-2)
+ *   - OpenRouterReranker  — https://openrouter.ai/api/v1/rerank (cohere/rerank-4-pro)
+ *   - OllamaReranker      — http://localhost:11434/api/chat (yes/no classification)
+ *
+ * API key resolution order (per provider):
+ *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
+ *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
+ */
+export interface RerankResult {
+    index: number;
+    score: number;
+    content: string;
+}
+export interface RerankerProvider {
+    readonly name: string;
+    /**
+     * Reranks `documents` by relevance to `query`.
+     * Returns null on any failure — callers MUST fall back to original order.
+     */
+    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
+}
+export interface RerankerConfig {
+    provider: 'zeroentropy' | 'openrouter' | 'local' | 'none';
+    minCandidates: number;
+    maxDocuments: number;
+    topK: number;
+    timeoutMs: number;
+    zeroEntropyApiKey?: string;
+    zeroEntropyModel?: string;
+    openrouterApiKey?: string;
+    openrouterModel?: string;
+    ollamaUrl?: string;
+    ollamaModel?: string;
+}
+export declare class ZeroEntropyReranker implements RerankerProvider {
+    readonly name = "zeroentropy";
+    private readonly circuit;
+    private readonly apiKey;
+    private readonly model;
+    private readonly timeoutMs;
+    constructor(apiKey: string, model?: string, timeoutMs?: number);
+    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
+}
+export declare class OpenRouterReranker implements RerankerProvider {
+    readonly name = "openrouter";
+    private readonly circuit;
+    private readonly apiKey;
+    private readonly model;
+    private readonly timeoutMs;
+    constructor(apiKey: string, model?: string, timeoutMs?: number);
+    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
+}
+export declare class OllamaReranker implements RerankerProvider {
+    readonly name = "ollama";
+    private readonly circuit;
+    private readonly baseUrl;
+    private readonly model;
+    private readonly timeoutMs;
+    constructor(baseUrl?: string, model?: string, timeoutMs?: number);
+    /**
+     * Scores documents sequentially — one chat call per document.
+     * The Qwen3-Reranker-0.6B model responds with "yes" (relevant) or "no".
+     * Score: yes → 1.0, anything else → 0.0.
+     *
+     * Sequential iteration is required because Ollama's /api/chat is stateless
+     * per-request and running calls in parallel would overload a local GPU.
+     * Returns null on the first failure to preserve circuit breaker semantics.
+     */
+    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
+}
+/**
+ * Creates a RerankerProvider from the supplied config.
+ *
+ * API key resolution order:
+ *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
+ *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
+ *
+ * Returns null when:
+ *   - provider is 'none'
+ *   - provider is 'zeroentropy' and no key found in config or env
+ *   - provider is 'openrouter' and no key found in config or env
+ *
+ * 'local' (Ollama) never returns null from the factory — it has no required
+ * API key. The provider itself returns null on runtime failure.
+ */
+export declare function createReranker(config: RerankerConfig): RerankerProvider | null;
+//# sourceMappingURL=reranker.d.ts.map

package/dist/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../src/reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgFH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,aAAa,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,KAAK,SAAa,EAAE,SAAS,SAAO;IAM1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CAqC5F;AAID,qBAAa,kBAAmB,YAAW,gBAAgB;IACzD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,KAAK,SAAwB,EAAE,SAAS,SAAO;IAMrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CAqC5F;AAQD,qBAAa,cAAe,YAAW,gBAAgB;IACrD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGjC,OAAO,SAA2B,EAClC,KAAK,SAAuC,EAC5C,SAAS,SAAS;IAOpB;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CA4C5F;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,IAAI,CAyB9E"}