@psiclawops/hypermem 0.7.0 → 0.8.1

package/dist/library-schema.js

@@ -16,7 +16,10 @@
  *   9. Work items (fleet kanban)
  *  10. Topics (cross-session thread tracking)
  */
-export const LIBRARY_SCHEMA_VERSION = 15;
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, renameSync, existsSync } from 'node:fs';
+import { join as pathJoin, dirname } from 'node:path';
+export const LIBRARY_SCHEMA_VERSION = 19;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -321,6 +324,7 @@ function applyV3Collections(db) {
     )
   `);
     db.exec('CREATE INDEX IF NOT EXISTS idx_topics_agent ON topics(agent_id, status, updated_at DESC)');
+    db.exec('CREATE UNIQUE INDEX IF NOT EXISTS idx_topics_dedup ON topics(agent_id, lower(name))');
     // ── Fleet registry ──
     db.exec(`
     CREATE TABLE IF NOT EXISTS fleet_agents (
@@ -868,6 +872,92 @@ function applyV12FosMod(db) {
         }
     }
 }
+// ── Repair utility ───────────────────────────────────────────
+// Safe to call BEFORE opening the main DB connection.
+// Handles the case where library.db has duplicate topics AND B-tree corruption,
+// making in-place DELETE impossible.
+//
+// Strategy:
+//   1. Detect duplicates (read-only: works on corrupt DBs)
+//   2. VACUUM INTO temp file (writes to a new clean file)
+//   3. Dedup + integrity check in temp
+//   4. Backup original via VACUUM INTO backups dir
+//   5. Atomic rename temp → original
+export function repairLibraryDb(dbPath) {
+    if (!existsSync(dbPath)) {
+        return { repaired: false, message: `DB not found at ${dbPath}. Nothing to repair.` };
+    }
+    const backupsDir = pathJoin(dirname(dbPath), 'backups');
+    const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const tempPath = `${dbPath}.repair-${ts}.sqlite`;
+    const backupPath = pathJoin(backupsDir, `library.db.pre-repair-${ts}.sqlite`);
+    const src = new DatabaseSync(dbPath);
+    // Step 1: detect duplicates
+    const dupeRow = src.prepare(`
+    SELECT COUNT(*) AS cnt FROM (
+      SELECT agent_id, lower(name) FROM topics
+      GROUP BY agent_id, lower(name) HAVING COUNT(*) > 1
+    )
+  `).get();
+    if (dupeRow.cnt === 0) {
+        src.close();
+        return { repaired: false, message: 'No duplicate topics found. No repair needed.' };
+    }
+    console.log(`[hypermem-repair] ${dupeRow.cnt} duplicate topic group(s) found. Starting repair...`);
+    // Step 2: VACUUM INTO temp (reads clean pages, writes fresh file)
+    try {
+        src.exec(`VACUUM INTO '${tempPath}'`);
+    }
+    catch (err) {
+        src.close();
+        throw new Error(`[hypermem-repair] VACUUM INTO failed: ${err.message}. Cannot auto-repair.`);
+    }
+    src.close();
+    // Step 3: dedup + verify in temp
+    const tmp = new DatabaseSync(tempPath);
+    try {
+        tmp.exec(`
+      DELETE FROM topics WHERE id IN (
+        WITH ranked AS (
+          SELECT id, ROW_NUMBER() OVER (
+            PARTITION BY agent_id, lower(name)
+            ORDER BY updated_at DESC, created_at DESC, id DESC
+          ) AS rn FROM topics
+        )
+        SELECT id FROM ranked WHERE rn > 1
+      )
+    `);
+        tmp.exec('CREATE UNIQUE INDEX IF NOT EXISTS idx_topics_dedup ON topics(agent_id, lower(name))');
+        const integ = tmp.prepare('PRAGMA integrity_check').get();
+        if (integ.integrity_check !== 'ok') {
+            throw new Error(`Repaired DB failed integrity check: ${integ.integrity_check}`);
+        }
+    }
+    finally {
+        tmp.close();
+    }
+    // Step 4: backup original
+    mkdirSync(backupsDir, { recursive: true });
+    let savedBackup = false;
+    try {
+        const srcForBackup = new DatabaseSync(dbPath);
+        srcForBackup.exec(`VACUUM INTO '${backupPath}'`);
+        srcForBackup.close();
+        savedBackup = true;
+        console.log(`[hypermem-repair] Backup saved → ${backupPath}`);
+    }
+    catch {
+        console.warn('[hypermem-repair] Could not save backup, proceeding with repair anyway.');
+    }
+    // Step 5: atomic swap
+    renameSync(tempPath, dbPath);
+    const msg = [
+        `Repair complete. ${dupeRow.cnt} duplicate topic group(s) removed.`,
+        savedBackup ? `Original backed up to: ${backupPath}` : 'Note: backup could not be saved.',
+    ].join(' ');
+    console.log(`[hypermem-repair] ${msg}`);
+    return { repaired: true, backupPath: savedBackup ? backupPath : undefined, message: msg };
+}
 // ── Migration runner ──────────────────────────────────────────
 export function migrateLibrary(db, engineVersion) {
     db.exec(`
@@ -1086,6 +1176,151 @@ export function migrateLibrary(db, engineVersion) {
         db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
             .run(15, nowIso());
     }
+    if (currentVersion < 16) {
+        // contradiction_audits table — tracks detected contradictions for review
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS contradiction_audits (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id TEXT NOT NULL,
+        entity_type TEXT NOT NULL CHECK(entity_type IN ('fact')),
+        new_content TEXT NOT NULL,
+        new_domain TEXT,
+        existing_fact_id INTEGER NOT NULL,
+        existing_content TEXT NOT NULL,
+        similarity_score REAL NOT NULL,
+        contradiction_score REAL NOT NULL,
+        reason TEXT NOT NULL,
+        detector TEXT NOT NULL DEFAULT 'heuristic_v1',
+        suggested_resolution TEXT NOT NULL DEFAULT 'review',
+        source_ref TEXT,
+        status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'accepted', 'dismissed')),
+        resolution_notes TEXT,
+        created_at TEXT NOT NULL,
+        resolved_at TEXT
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_contradiction_audits_agent_status ON contradiction_audits(agent_id, status, created_at DESC)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_contradiction_audits_existing_fact ON contradiction_audits(existing_fact_id, status)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_contradiction_audits_agent ON contradiction_audits(agent_id, created_at DESC)');
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(16, nowIso());
+    }
+    if (currentVersion < 17) {
+        // Stamp v17 — previously applied by an older engine build alongside contradiction_audits.
+        // No additional DDL needed; the table was already created in v16.
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(17, nowIso());
+    }
+    if (currentVersion < 18) {
+        // V18: collapse duplicate topics, then enforce unique constraint.
+        //
+        // Safety pattern for existing users who may have both duplicates AND B-tree corruption
+        // (e.g. from a WAL desync during a gateway crash):
+        //  1. Detect duplicates up front (read-only — works even on malformed DBs)
+        //  2. If dupes found: VACUUM INTO a backup file first (reads clean pages, writes new file)
+        //  3. Attempt in-place DELETE (works on healthy DBs)
+        //  4. If DELETE fails: throw a clear error pointing to the backup + repair command
+        const dupeCheck = db.prepare(`
+      SELECT COUNT(*) AS cnt FROM (
+        SELECT agent_id, lower(name) FROM topics
+        GROUP BY agent_id, lower(name) HAVING COUNT(*) > 1
+      )
+    `).get();
+        let v18BackupPath;
+        if (dupeCheck.cnt > 0) {
+            // Auto-backup via VACUUM INTO before any writes.
+            // VACUUM INTO reads clean pages and writes to a new file — works even on marginally
+            // corrupt DBs where regular writes fail.
+            const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '';
+            const backupsDir = pathJoin(home, '.openclaw', 'hypermem', 'backups');
+            const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            v18BackupPath = pathJoin(backupsDir, `library.db.v18-pre-dedup-${ts}.sqlite`);
+            try {
+                mkdirSync(backupsDir, { recursive: true });
+                db.exec(`VACUUM INTO '${v18BackupPath}'`);
+                console.log(`[hypermem-library] V18: backup saved → ${v18BackupPath}`);
+            }
+            catch (e) {
+                console.warn(`[hypermem-library] V18: backup failed (${e.message}), proceeding without backup`);
+                v18BackupPath = undefined;
+            }
+            try {
+                db.exec(`
+          DELETE FROM topics
+          WHERE id IN (
+            WITH ranked AS (
+              SELECT
+                id,
+                ROW_NUMBER() OVER (
+                  PARTITION BY agent_id, lower(name)
+                  ORDER BY updated_at DESC, created_at DESC, id DESC
+                ) AS rn
+              FROM topics
+            )
+            SELECT id FROM ranked WHERE rn > 1
+          )
+        `);
+            }
+            catch (err) {
+                const backupMsg = v18BackupPath
+                    ? `A VACUUM backup was saved to:\n  ${v18BackupPath}\nRun: hypermem repair-library to recover automatically.`
+                    : 'Run: hypermem repair-library to recover.';
+                throw new Error(`[hypermem-library] V18 migration: failed to deduplicate topics (${err.message}).\n` +
+                    `Your library.db has ${dupeCheck.cnt} duplicate topic group(s) that could not be removed in-place.\n` +
+                    `This usually indicates B-tree corruption from a previous gateway crash.\n` +
+                    backupMsg);
+            }
+        }
+        db.exec('CREATE UNIQUE INDEX IF NOT EXISTS idx_topics_dedup ON topics(agent_id, lower(name))');
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(18, nowIso());
+    }
+    if (currentVersion < 19) {
+        // V19: Extend contradiction_audits status CHECK constraint to include
+        // auto-resolution values. SQLite cannot ALTER CHECK constraints — recreate
+        // the table with the new constraint, preserving all existing rows.
+        // Use an explicit column list (not SELECT *) to guard against column drift.
+        db.exec(`
+      CREATE TABLE contradiction_audits_v19 (
+        id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id            TEXT NOT NULL,
+        entity_type         TEXT NOT NULL CHECK(entity_type IN ('fact')),
+        new_content         TEXT NOT NULL,
+        new_domain          TEXT,
+        existing_fact_id    INTEGER NOT NULL,
+        existing_content    TEXT NOT NULL,
+        similarity_score    REAL NOT NULL,
+        contradiction_score REAL NOT NULL,
+        reason              TEXT NOT NULL,
+        detector            TEXT NOT NULL DEFAULT 'heuristic_v1',
+        suggested_resolution TEXT NOT NULL DEFAULT 'review',
+        source_ref          TEXT,
+        status              TEXT NOT NULL DEFAULT 'pending'
+          CHECK(status IN ('pending', 'accepted', 'dismissed', 'auto-superseded', 'auto-invalidated')),
+        resolution_notes    TEXT,
+        created_at          TEXT NOT NULL,
+        resolved_at         TEXT
+      );
+      INSERT INTO contradiction_audits_v19
+        (id, agent_id, entity_type, new_content, new_domain, existing_fact_id,
+         existing_content, similarity_score, contradiction_score, reason,
+         detector, suggested_resolution, source_ref, status, resolution_notes,
+         created_at, resolved_at)
+      SELECT
+        id, agent_id, entity_type, new_content, new_domain, existing_fact_id,
+        existing_content, similarity_score, contradiction_score, reason,
+        detector, suggested_resolution, source_ref, status, resolution_notes,
+        created_at, resolved_at
+      FROM contradiction_audits;
+      DROP TABLE contradiction_audits;
+      ALTER TABLE contradiction_audits_v19 RENAME TO contradiction_audits;
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_contradiction_audits_agent_status ON contradiction_audits(agent_id, status, created_at DESC)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_contradiction_audits_existing_fact ON contradiction_audits(existing_fact_id, status)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_contradiction_audits_agent ON contradiction_audits(agent_id, created_at DESC)');
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(19, nowIso());
+    }
     // Always ensure meta exists before stamping the running engine version.
     // Some legacy/stale DBs reached schema >=10 without the V10 migration having
     // actually created the table, which would make startup fail with

package/dist/message-store.d.ts

@@ -6,7 +6,7 @@
  * This is the write-through layer: Redis → here.
  */
 import type { DatabaseSync } from 'node:sqlite';
-import type { NeutralMessage, StoredMessage, Conversation, ChannelType, ConversationStatus, RecentTurn } from './types.js';
+import type { NeutralMessage, StoredMessage, Conversation, ChannelType, ConversationStatus, RecentTurn, ArchivedMiningQuery, ArchivedMiningResult, MultiContextMiningOptions } from './types.js';
 export declare class MessageStore {
     private readonly db;
     constructor(db: DatabaseSync);
@@ -91,6 +91,12 @@ export declare 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: number, limit?: number): StoredMessage[];
     /**
@@ -110,6 +116,63 @@ export declare class MessageStore {
      * Get message count for a conversation.
      */
     getMessageCount(conversationId: number): number;
+    /**
+     * 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: number, limit?: number): StoredMessage[];
+    /**
+     * Default maximum number of contextIds accepted by mineArchivedContexts.
+     * Callers may supply a lower value but not a higher one.
+     */
+    static readonly 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 readonly ARCHIVED_MULTI_CONTEXT_HARD_CEILING = 50;
+    /**
+     * 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: ArchivedMiningQuery): ArchivedMiningResult<StoredMessage[]>;
+    /**
+     * 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: number[], opts?: MultiContextMiningOptions): ArchivedMiningResult<StoredMessage[]>[];
     /**
      * Infer channel type from session key format.
      */

package/dist/message-store.d.ts.map

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

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/open-domain.js

@@ -61,7 +61,7 @@ export function buildOpenDomainFtsQuery(query) {
         .split(/\s+/)
         .filter(w => w.length >= 3 && !STOP_WORDS.has(w))
         .slice(0, 6)
-        .map(w => `${w}*`);
+        .map(w => `"${w}"*`);
     if (terms.length === 0)
         return null;
     return terms.join(' OR ');

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"}