@psiclawops/hypermem 0.6.2 → 0.8.0

package/dist/knowledge-lint.js

@@ -7,6 +7,9 @@
  *  3. Coverage gaps — topics with many messages but no synthesis
  */
 import { LINT_STALE_DAYS } from './topic-synthesizer.js';
+// Orphan topics older than this many days are eligible for pruning.
+// 48h = report threshold, 14d = prune threshold (conservative).
+export const ORPHAN_PRUNE_DAYS = 14;
 // ─── lintKnowledge ──────────────────────────────────────────────
 /**
  * Run lint checks on the knowledge table.
@@ -25,6 +28,7 @@ export function lintKnowledge(libraryDb) {
     const result = {
         staleDecayed: 0,
         orphansFound: 0,
+        orphansPruned: 0,
         coverageGaps: [],
     };
     // ── 1. Stale syntheses ─────────────────────────────────────────
@@ -80,7 +84,42 @@ export function lintKnowledge(libraryDb) {
     `).all();
         result.orphansFound = orphans.length;
         if (orphans.length > 0) {
-            console.log(`[lint] ${orphans.length} orphan topic(s) found (< 3 messages, stale > 48h): ${orphans.map(o => o.name).join(', ')}`);
+            const sample = orphans.slice(0, 10).map(o => o.name).join(', ');
+            const remainder = Math.max(0, orphans.length - 10);
+            console.log(`[lint] ${orphans.length} orphan topic(s) found (< 3 messages, stale > 48h)` +
+                (sample ? `; sample: ${sample}` : '') +
+                (remainder > 0 ? `; +${remainder} more` : ''));
+        }
+        // Prune orphan topics older than ORPHAN_PRUNE_DAYS (conservative cleanup).
+        // Safety: only prune topics with no knowledge-synthesis entries and no facts
+        // referencing them (via source_ref 'topic:<id>' pattern).
+        try {
+            const prunable = libraryDb.prepare(`
+        SELECT t.id, t.name FROM topics t
+        WHERE t.message_count < 3
+          AND t.updated_at < datetime('now', '-' || ? || ' days')
+          AND NOT EXISTS (
+            SELECT 1 FROM knowledge k
+            WHERE k.agent_id = t.agent_id
+              AND k.domain = 'topic-synthesis'
+              AND k.key = t.name
+              AND k.superseded_by IS NULL
+          )
+          AND NOT EXISTS (
+            SELECT 1 FROM facts f
+            WHERE f.source_ref LIKE 'topic:' || t.id || '%'
+          )
+      `).all(ORPHAN_PRUNE_DAYS);
+            if (prunable.length > 0) {
+                const ids = prunable.map(p => p.id);
+                const placeholders = ids.map(() => '?').join(',');
+                libraryDb.prepare(`DELETE FROM topics WHERE id IN (${placeholders})`).run(...ids);
+                result.orphansPruned = prunable.length;
+                console.log(`[lint] pruned ${prunable.length} orphan topic(s) (< 3 messages, stale > ${ORPHAN_PRUNE_DAYS}d, no syntheses or facts)`);
+            }
+        }
+        catch (err) {
+            console.warn('[lint] orphan prune failed (non-fatal):', err.message);
         }
     }
     catch {

package/dist/library-schema.d.ts

@@ -16,7 +16,12 @@
  *   9. Work items (fleet kanban)
  *  10. Topics (cross-session thread tracking)
  */
-import type { DatabaseSync } from 'node:sqlite';
-export declare const LIBRARY_SCHEMA_VERSION = 13;
+import { DatabaseSync } from 'node:sqlite';
+export declare const LIBRARY_SCHEMA_VERSION = 19;
+export declare function repairLibraryDb(dbPath: string): {
+    repaired: boolean;
+    backupPath?: string;
+    message: string;
+};
 export declare function migrateLibrary(db: DatabaseSync, engineVersion?: string): void;
 //# sourceMappingURL=library-schema.d.ts.map

package/dist/library-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library-schema.d.ts","sourceRoot":"","sources":["../src/library-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAs5BzC,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CA8L7E"}
+{"version":3,"file":"library-schema.d.ts","sourceRoot":"","sources":["../src/library-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAo6BzC,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAkF3G;AAID,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAuZ7E"}

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 = 13;
+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();
 }
@@ -150,12 +153,15 @@ function applyV3Collections(db) {
       updated_at TEXT NOT NULL,
       expires_at TEXT,
       superseded_by INTEGER,
-      decay_score REAL DEFAULT 0.0
+      decay_score REAL DEFAULT 0.0,
+      valid_from TEXT,
+      invalid_at TEXT
     )
   `);
     db.exec('CREATE INDEX IF NOT EXISTS idx_facts_agent ON facts(agent_id, scope, domain)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_facts_visibility ON facts(visibility, agent_id)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_facts_active ON facts(agent_id, superseded_by, decay_score, confidence DESC)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_facts_temporal_validity ON facts(agent_id, valid_from, invalid_at)');
     db.exec(`
     CREATE VIRTUAL TABLE IF NOT EXISTS facts_fts USING fts5(
       content,
@@ -318,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 (
@@ -865,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(`
@@ -1016,6 +1109,218 @@ export function migrateLibrary(db, engineVersion) {
         db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
             .run(13, nowIso());
     }
+    // ── V14: Temporal validity columns on facts ──────────────────────────
+    // valid_from / invalid_at enable "what was true on date X?" queries.
+    if (currentVersion < 14) {
+        try {
+            db.exec('ALTER TABLE facts ADD COLUMN valid_from TEXT');
+        }
+        catch { /* already exists */ }
+        try {
+            db.exec('ALTER TABLE facts ADD COLUMN invalid_at TEXT');
+        }
+        catch { /* already exists */ }
+        try {
+            db.exec('CREATE INDEX IF NOT EXISTS idx_facts_temporal_validity ON facts(agent_id, valid_from, invalid_at)');
+        }
+        catch { /* already exists */ }
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(14, nowIso());
+    }
+    // ── V15: Expertise tables (domain expertise patterns) ──────────────
+    // expertise_observations: raw learnings from conversations, pipelines, reviews
+    // expertise_patterns: graduated observations with confirming evidence
+    // expertise_evidence: links observations to patterns (confirms/contradicts)
+    if (currentVersion < 15) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS expertise_observations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id TEXT NOT NULL,
+        domain TEXT NOT NULL,
+        context TEXT,
+        observation_text TEXT NOT NULL,
+        source_type TEXT NOT NULL DEFAULT 'conversation',
+        source_ref TEXT,
+        created_at TEXT NOT NULL
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_expertise_obs_agent ON expertise_observations(agent_id, domain)');
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS expertise_patterns (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id TEXT NOT NULL,
+        domain TEXT NOT NULL,
+        pattern_text TEXT NOT NULL,
+        confidence REAL DEFAULT 0.7,
+        frequency INTEGER DEFAULT 1,
+        first_seen TEXT NOT NULL,
+        last_confirmed TEXT NOT NULL,
+        invalidated_at TEXT,
+        invalidation_reason TEXT,
+        decay_score REAL DEFAULT 0.0,
+        updated_at TEXT
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_expertise_patterns_agent ON expertise_patterns(agent_id, domain, invalidated_at)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_expertise_patterns_active ON expertise_patterns(agent_id, invalidated_at, confidence DESC)');
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS expertise_evidence (
+        observation_id INTEGER NOT NULL,
+        pattern_id INTEGER NOT NULL,
+        relationship TEXT NOT NULL CHECK(relationship IN ('confirms', 'contradicts')),
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (observation_id, pattern_id)
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_expertise_evidence_pattern ON expertise_evidence(pattern_id, relationship)');
+        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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"}