agentic-qe 3.15.8 → 3.15.10

package/dist/learning/dream/dream-engine.js

@@ -25,7 +25,8 @@ import { registerStoreCloser } from '../../kernel/process-lifecycle.js';
 import { ConceptGraph } from './concept-graph.js';
 import { SpreadingActivation, } from './spreading-activation.js';
 import { InsightGenerator, } from './insight-generator.js';
-import { RVCOWBranchManager, DEFAULT_VALIDATION_THRESHOLDS, } from './rvcow-branch-manager.js';
+import { DEFAULT_VALIDATION_THRESHOLDS, } from './rvcow-branch-manager.js';
+import { commitDream, markAbandonedCycles, ABANDONED_CYCLE_GRACE_MS, } from './dream-commit.js';
 /**
  * Default DreamEngine configuration
  */
@@ -44,10 +45,24 @@ export const DEFAULT_DREAM_CONFIG = {
         minConfidence: 0.5,
         maxInsightsPerCycle: 10,
     },
-    // #1060: off by default; see the RISK note on DreamConfig.enableBranching.
+    // #1060: deprecated and ignored; see DreamConfig.enableBranching.
     enableBranching: false,
     branchValidationThresholds: { ...DEFAULT_VALIDATION_THRESHOLDS },
 };
+/**
+ * #1060: the longest dream the MCP tool runs (its durationMs cap). The
+ * abandoned-cycle sweep waits at least this long plus the grace period.
+ */
+const MAX_TOOL_DREAM_MS = 60_000;
+/** #1060: a second dream on the same engine while one is running. */
+export class DreamAlreadyRunningError extends Error {
+    cycleId;
+    constructor(cycleId) {
+        super(`A dream cycle is already running (cycle ${cycleId}); wait for it to finish or cancel it`);
+        this.cycleId = cycleId;
+        this.name = 'DreamAlreadyRunningError';
+    }
+}
 // ============================================================================
 // ConceptGraph Adapter
 // ============================================================================
@@ -64,6 +79,8 @@ class ConceptGraphAdapter {
     nodeCache = new Map();
     edgeCache = new Map();
     activationLevels = new Map();
+    /** #1060: each node's level when loaded, for the commit's conflict check. */
+    loadedLevels = new Map();
     constructor(graph) {
         this.graph = graph;
     }
@@ -77,6 +94,7 @@ class ConceptGraphAdapter {
         this.nodeCache.clear();
         this.edgeCache.clear();
         this.activationLevels.clear();
+        this.loadedLevels.clear();
         // Load nodes (all or capped)
         let nodes = await this.graph.getActiveNodes(0);
         if (maxNodes && nodes.length > maxNodes) {
@@ -87,6 +105,7 @@ class ConceptGraphAdapter {
         for (const node of nodes) {
             this.nodeCache.set(node.id, node);
             this.activationLevels.set(node.id, node.activationLevel);
+            this.loadedLevels.set(node.id, node.activationLevel);
         }
         // Load edges for each node
         for (const node of nodes) {
@@ -96,13 +115,17 @@ class ConceptGraphAdapter {
         }
     }
     /**
-     * Persist activation levels back to the database
+     * Final activation levels with the levels loaded, written by commitDream()
+     * in the cycle's single transaction (#1060) instead of one awaited UPDATE
+     * per node. The loaded level lets the commit skip a node a foreground write
+     * changed during the dream.
      */
-    async persistActivations() {
-        const entries = Array.from(this.activationLevels.entries());
-        for (const [nodeId, level] of entries) {
-            await this.graph.updateActivation(nodeId, level);
-        }
+    activationEntries() {
+        return Array.from(this.activationLevels.entries(), ([id, level]) => [
+            id,
+            level,
+            this.loadedLevels.get(id),
+        ]);
     }
     // SpreadingConceptGraph interface implementation
     getConcept(id) {
@@ -207,21 +230,26 @@ export class DreamEngine {
     persistence = null;
     graph = null;
     db = null;
-    branchManager = null;
     /** #1060: marks the in-flight dream cycle interrupted (set while dreaming). */
     interruptActiveDream = null;
+    /** #1060: the in-flight dream, so close() can wait for it to stop. */
+    activeDream = null;
+    /** #1060: stops the in-flight dream's activation loop. */
+    activeAbort = null;
     currentCycle = null;
     initialized = false;
     cancelled = false;
+    /** #1060: how many times cancelDream() was called (see cancelCount). */
+    cancelRequests = 0;
+    /** #1060: set by close() until the engine is initialized again. */
+    closing = false;
     branchEventListeners = [];
     /** Optional witness chain for audit trail of dream decisions (ADR-070) */
     _witnessChain = null;
     set witnessChain(wc) { this._witnessChain = wc; }
-    /** Optional RVF adapter for COW branching (ADR-069). Set externally to share with PatternStore. */
+    /** @deprecated #1060: branching is ignored, so the RVF adapter is unused. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    _rvfAdapter = null;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    set rvfAdapter(adapter) { this._rvfAdapter = adapter; }
+    set rvfAdapter(_adapter) { }
     constructor(config) {
         this.config = { ...DEFAULT_DREAM_CONFIG, ...config };
     }
@@ -253,17 +281,18 @@ export class DreamEngine {
             // Initialize concept graph (shares same unified persistence)
             this.graph = new ConceptGraph();
             await this.graph.initialize();
-            // Initialize RVCOW branch manager (ADR-069)
+            // #1060: branching is deprecated; dream results commit in one transaction.
             if (this.config.enableBranching) {
-                this.branchManager = new RVCOWBranchManager(this.db, this.config.branchValidationThresholds);
-                // ADR-069: Wire RVF adapter for true COW branching when available
-                // Uses externally-provided adapter to avoid duplicate file handles
-                if (this._rvfAdapter) {
-                    this.branchManager.setRvfAdapter(this._rvfAdapter, true);
-                    console.log('[DreamEngine] RVF COW branching activated (ADR-069)');
-                }
+                dreamLogger.warn('DreamConfig.enableBranching is deprecated and ignored (#1060): dream results are ' +
+                    'committed in one short transaction instead of a SAVEPOINT held across the dream');
+            }
+            // #1060: a process that exited mid-dream left its cycle 'running'.
+            const abandoned = markAbandonedCycles(this.db, Math.max(this.config.maxDurationMs, MAX_TOOL_DREAM_MS) + ABANDONED_CYCLE_GRACE_MS);
+            if (abandoned > 0) {
+                dreamLogger.info('Marked abandoned dream cycles as interrupted', { abandoned });
             }
             this.initialized = true;
+            this.closing = false;
             console.log(`[DreamEngine] Initialized: ${this.persistence.getDbPath()}`);
         }
         catch (error) {
@@ -330,16 +359,27 @@ export class DreamEngine {
      * 4. Generates insights from activation patterns
      * 5. Persists the cycle and insights
      *
+     * The cycle row is written as 'running' when the dream starts. Another
+     * process's DreamEngine.initialize() marks a cycle still 'running' after
+     * max(its config.maxDurationMs, 60 s) + ABANDONED_CYCLE_GRACE_MS (10 min),
+     * i.e. 11 minutes by default, as interrupted ('abandoned: process exited').
+     * The MCP tool and the CLI cap dreams at 60 s. A library caller that runs
+     * dreams longer than about 10 minutes (graph loading included) should give
+     * every engine sharing the database a maxDurationMs at least that long, or
+     * a live cycle can be marked interrupted. Its commit still records the
+     * final status, and nothing is deleted.
+     *
      * @param durationMs - Maximum duration in milliseconds (default: config.maxDurationMs)
      * @returns Dream cycle result with insights and statistics
      */
-    async dream(durationMs) {
+    async dream(durationMs, options = {}) {
         this.ensureInitialized();
-        this.cancelled = false;
-        const maxDuration = durationMs ?? this.config.maxDurationMs;
-        const startTime = Date.now();
-        // Create cycle record
-        this.currentCycle = {
+        if (this.closing)
+            throw new Error('Dream engine is closing; no new dream is started');
+        // #1060: one dream at a time per engine; a second request is refused.
+        if (this.activeDream)
+            throw new DreamAlreadyRunningError(this.activeDream.cycleId);
+        const cycle = {
             id: uuidv4(),
             startTime: new Date(),
             conceptsProcessed: 0,
@@ -347,92 +387,81 @@ export class DreamEngine {
             insightsGenerated: 0,
             status: 'running',
         };
-        await this.saveCycle(this.currentCycle);
-        // ADR-069: Create RVCOW branch before dream consolidation (opt-in, #1060)
-        let branch = null;
-        if (this.branchManager) {
-            const branchName = `dream-${this.currentCycle.id}-${Date.now()}`;
-            branch = this.branchManager.createBranch(branchName);
-            this.emitBranchEvent('dream:branch_created', branch);
+        const run = this.runDream(cycle, durationMs ?? this.config.maxDurationMs, options);
+        this.activeDream = { cycleId: cycle.id, done: run.catch(() => undefined) };
+        try {
+            return await run;
         }
-        // #1060: if the engine closes or the process shuts down mid-dream, record
-        // the cycle as interrupted instead of leaving it 'running' forever.
-        const interrupt = this.createCycleInterrupter(this.currentCycle, startTime, () => branch);
+        finally {
+            if (this.activeDream?.cycleId === cycle.id)
+                this.activeDream = null;
+        }
+    }
+    /**
+     * #1060: compute, then commit. Everything up to the commit reads the
+     * database or works in memory; the results are written by commitDream() in
+     * one synchronous transaction, so no lock is held across an await and no
+     * foreground write can join the dream's writes or be rolled back with them.
+     */
+    async runDream(cycle, maxDuration, options) {
+        const db = this.db;
+        const graph = this.graph;
+        const startTime = Date.now();
+        const abort = new AbortController();
+        this.activeAbort = abort;
+        this.cancelled = false;
+        this.currentCycle = cycle;
+        const commitResults = options.commit !== false;
+        // If the engine closes or the process shuts down mid-dream, stop the dream
+        // and record the cycle as interrupted instead of leaving it 'running'.
+        // Registered before the first await, so a close() or shutdown right after
+        // dream() is called still reaches this dream.
+        const interrupt = this.createCycleInterrupter(cycle, startTime, abort);
         this.interruptActiveDream = interrupt;
         const unregisterShutdownGuard = registerStoreCloser(interrupt);
+        // The engine still owns this database and nobody asked the dream to stop.
+        const live = () => !this.cancelled && !abort.signal.aborted && this.db === db;
+        let committed = false;
         try {
+            if (commitResults)
+                await this.saveCycle(cycle);
+            if (!live())
+                throw new Error('Dream cycle cancelled');
             // 1. Check we have enough concepts
-            const allNodes = await this.graph.getActiveNodes(0);
-            if (allNodes.length < this.config.minConceptsRequired) {
-                throw new Error(`Insufficient concepts: ${allNodes.length} < ${this.config.minConceptsRequired}`);
+            const minConcepts = options.minConceptsRequired ?? this.config.minConceptsRequired;
+            const allNodes = await graph.getActiveNodes(0);
+            if (allNodes.length < minConcepts) {
+                throw new Error(`Insufficient concepts: ${allNodes.length} < ${minConcepts}`);
             }
-            // 2. Create adapter and load graph into memory.
-            //    Cap nodes to keep wall-clock time reasonable on large concept graphs.
-            //    Each node requires DB queries for edges (O(N) queries per node),
-            //    so fewer nodes significantly reduces initialization time.
-            const adapter = new ConceptGraphAdapter(this.graph);
+            // 2. Load the graph into memory. Each node requires DB queries for
+            //    edges, so the node count is capped to keep wall-clock time reasonable.
+            const adapter = new ConceptGraphAdapter(graph);
             await adapter.loadIntoMemory(30);
-            // 3. Run spreading activation (the "dreaming")
-            const activation = new SpreadingActivation(adapter, this.config.activationConfig);
-            const activationResult = await activation.dream(maxDuration);
-            // Check for cancellation
-            if (this.cancelled) {
-                this.currentCycle.status = 'interrupted';
-                this.currentCycle.endTime = new Date();
-                this.currentCycle.durationMs = Date.now() - startTime;
-                await this.updateCycle(this.currentCycle);
+            // 3. Spreading activation (the "dreaming"), in memory only.
+            const activation = new SpreadingActivation(adapter, {
+                ...this.config.activationConfig,
+                ...options.activationConfig,
+            });
+            const activationResult = await activation.dream(maxDuration, abort.signal);
+            if (!live())
                 throw new Error('Dream cycle cancelled');
-            }
-            this.currentCycle.conceptsProcessed = activationResult.nodesActivated;
-            this.currentCycle.associationsFound = activationResult.novelAssociations.length;
-            // 4. Persist activation levels
-            await adapter.persistActivations();
-            // 5. Generate insights from activation
+            cycle.conceptsProcessed = activationResult.nodesActivated;
+            cycle.associationsFound = activationResult.novelAssociations.length;
+            // 4. Insights, in memory only.
             const generator = new InsightGenerator(adapter, this.config.insightConfig);
-            const insights = await generator.generateFromActivation(this.currentCycle.id, activationResult);
-            this.currentCycle.insightsGenerated = insights.length;
-            // 6. Save insights
-            for (const insight of insights) {
-                await this.saveInsight(insight);
-            }
-            // 7. Finalize cycle
-            this.currentCycle.endTime = new Date();
-            this.currentCycle.durationMs = Date.now() - startTime;
-            this.currentCycle.status = 'completed';
-            await this.updateCycle(this.currentCycle);
-            // ADR-069: Validate and merge/discard the RVCOW branch
-            if (branch && this.branchManager) {
-                const validation = this.branchManager.validateBranch(branch);
-                if (validation.passed) {
-                    this.branchManager.mergeBranch(branch);
-                    this.emitBranchEvent('dream:branch_merged', branch, validation);
-                    try {
-                        this._witnessChain?.append('DREAM_MERGE', {
-                            cycleId: this.currentCycle.id, branchName: branch.name,
-                        }, 'dream-engine');
-                    }
-                    catch { /* best-effort witness */ }
-                }
-                else {
-                    this.branchManager.discardBranch(branch);
-                    this.emitBranchEvent('dream:branch_discarded', branch, validation);
-                    try {
-                        this._witnessChain?.append('DREAM_DISCARD', {
-                            cycleId: this.currentCycle.id, branchName: branch.name,
-                            reason: validation.reason,
-                        }, 'dream-engine');
-                    }
-                    catch { /* best-effort witness */ }
-                    dreamLogger.warn('Dream branch discarded: quality validation failed', {
-                        cycleId: this.currentCycle.id,
-                        reason: validation.reason,
-                    });
-                    // Still return results so caller sees what happened
-                }
-                branch = null; // Prevent double-discard in catch
-            }
+            const insights = await generator.generateFromActivation(cycle.id, activationResult);
+            if (!live())
+                throw new Error('Dream cycle cancelled');
+            // 5. Commit activations, insights and the final cycle row together.
+            //    live() was checked synchronously just above, so the dream is
+            //    still wanted and the engine still owns the database.
+            cycle.insightsGenerated = insights.length;
+            cycle.endTime = new Date();
+            cycle.durationMs = Date.now() - startTime;
+            cycle.status = 'completed';
+            const computed = { cycle, activations: adapter.activationEntries(), insights };
             const result = {
-                cycle: { ...this.currentCycle },
+                cycle: { ...cycle },
                 insights,
                 activationStats: {
                     totalIterations: activationResult.iterations,
@@ -441,59 +470,93 @@ export class DreamEngine {
                 },
                 patternsCreated: 0, // Updated when insights are applied
             };
-            this.currentCycle = null;
+            if (!commitResults) {
+                committed = true; // nothing to record: the caller decides
+                return { ...result, pending: computed };
+            }
+            result.commitDurationMs = this.commitComputed(db, computed);
+            committed = true;
             return result;
         }
         catch (error) {
-            // ADR-069: Discard branch on error to ensure no partial mutations persist
-            if (branch && this.branchManager) {
-                try {
-                    this.branchManager.discardBranch(branch);
-                    this.emitBranchEvent('dream:branch_discarded', branch);
-                }
-                catch {
-                    // Branch may already be discarded; ignore
+            // Nothing of the dream was committed. An interrupted cycle was already
+            // recorded by the interrupter; anything else is recorded as failed.
+            if (!committed && cycle.status !== 'interrupted') {
+                cycle.status = this.cancelled ? 'interrupted' : 'failed';
+                cycle.error = toErrorMessage(error);
+                cycle.endTime = new Date();
+                cycle.durationMs = Date.now() - startTime;
+                if (commitResults && this.db === db) {
+                    try {
+                        this.updateCycleSync(cycle);
+                    }
+                    catch { /* best effort */ }
                 }
             }
-            if (this.currentCycle) {
-                if (this.currentCycle.status === 'running') {
-                    this.currentCycle.status = 'failed';
+            if (!committed && commitResults) {
+                try {
+                    this._witnessChain?.append('DREAM_DISCARD', {
+                        cycleId: cycle.id, reason: toErrorMessage(error),
+                    }, 'dream-engine');
                 }
-                this.currentCycle.error = toErrorMessage(error);
-                this.currentCycle.endTime = new Date();
-                this.currentCycle.durationMs = Date.now() - startTime;
-                await this.updateCycle(this.currentCycle);
+                catch { /* best-effort witness */ }
             }
-            this.currentCycle = null;
             throw error;
         }
         finally {
             unregisterShutdownGuard();
             if (this.interruptActiveDream === interrupt)
                 this.interruptActiveDream = null;
+            if (this.currentCycle === cycle)
+                this.currentCycle = null;
+            if (this.activeAbort === abort)
+                this.activeAbort = null;
+        }
+    }
+    /**
+     * #1060: write the results of a `dream(…, { commit: false })` run, in the
+     * same single transaction a normal dream uses. Returns the commit duration
+     * in ms. Throws (and writes nothing) if the engine is closed or the write
+     * fails.
+     */
+    commitDreamResult(result) {
+        this.ensureInitialized();
+        if (this.closing) {
+            throw new Error('Dream engine is closing; nothing is committed');
+        }
+        if (!result.pending) {
+            throw new Error('Dream result has nothing pending to commit (it was already committed)');
         }
+        const duration = this.commitComputed(this.db, result.pending);
+        result.pending = undefined;
+        result.commitDurationMs = duration;
+        return duration;
+    }
+    /** Commit a computed dream, then record it in the witness chain (#1060). */
+    commitComputed(db, computed) {
+        const commit = commitDream(db, computed);
+        try {
+            this._witnessChain?.append('DREAM_COMMIT', {
+                cycleId: computed.cycle.id,
+                insights: commit.insightsWritten,
+                activations: commit.activationsWritten,
+                commitDurationMs: commit.commitDurationMs,
+            }, 'dream-engine');
+        }
+        catch { /* best-effort witness */ }
+        return commit.commitDurationMs;
     }
     /**
-     * #1060: build a synchronous handler that records a still-running cycle as
-     * 'interrupted'. It runs from close() and from a process store closer,
-     * which runs before the shared database closes (closers run newest first).
-     * When opt-in branching left a savepoint open, the savepoint is released
-     * first so foreground writes made on the shared connection during the
-     * dream are committed rather than lost with the connection.
+     * #1060: build a synchronous handler that stops a still-running dream and
+     * records its cycle as 'interrupted'. It runs from close() and from a
+     * process store closer, which runs before the shared database closes
+     * (closers run newest first). Nothing of the dream is committed afterwards.
      */
-    createCycleInterrupter(cycle, startTime, getBranch) {
+    createCycleInterrupter(cycle, startTime, abort) {
         return () => {
+            abort.abort();
             if (cycle.status !== 'running' || !this.db)
                 return;
-            const branch = getBranch();
-            if (branch && this.branchManager) {
-                try {
-                    this.branchManager.mergeBranch(branch);
-                }
-                catch {
-                    // Branch already resolved; nothing to release
-                }
-            }
             cycle.status = 'interrupted';
             cycle.error = 'Interrupted: engine closed or process shut down during the dream cycle';
             cycle.endTime = new Date();
@@ -767,11 +830,21 @@ export class DreamEngine {
     // ==========================================================================
     // Dream Control
     // ==========================================================================
+    /**
+     * #1060: number of cancelDream() calls so far. A caller that runs several
+     * dreams in a row (SpeculativeDreamer) compares it to stop after a cancel.
+     */
+    get cancelCount() {
+        return this.cancelRequests;
+    }
     /**
      * Cancel the running dream cycle.
      */
     async cancelDream() {
         this.cancelled = true;
+        this.cancelRequests++;
+        // #1060: stop the activation loop now; nothing of the dream is committed.
+        this.activeAbort?.abort();
     }
     /**
      * Check if a dream is currently running.
@@ -799,9 +872,6 @@ export class DreamEngine {
     `);
         stmt.run(cycle.id, cycle.startTime.toISOString(), cycle.endTime?.toISOString() ?? null, cycle.durationMs ?? null, cycle.conceptsProcessed, cycle.associationsFound, cycle.insightsGenerated, cycle.status, cycle.error ?? null, cycle.startTime.toISOString());
     }
-    async updateCycle(cycle) {
-        this.updateCycleSync(cycle);
-    }
     updateCycleSync(cycle) {
         if (!this.db)
             return;
@@ -813,19 +883,6 @@ export class DreamEngine {
     `);
         stmt.run(cycle.endTime?.toISOString() ?? null, cycle.durationMs ?? null, cycle.conceptsProcessed, cycle.associationsFound, cycle.insightsGenerated, cycle.status, cycle.error ?? null, cycle.id);
     }
-    async saveInsight(insight) {
-        if (!this.db)
-            return;
-        const stmt = this.db.prepare(`
-      INSERT INTO dream_insights
-      (id, cycle_id, insight_type, source_concepts, description, novelty_score,
-       confidence_score, actionable, applied, suggested_action, pattern_id)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `);
-        stmt.run(insight.id, insight.cycleId, insight.type, JSON.stringify(insight.sourceConcepts), insight.description, insight.noveltyScore, insight.confidenceScore, insight.actionable ? 1 : 0, 0, // Not applied yet
-        insight.suggestedAction ?? null, null // No pattern yet
-        );
-    }
     async getInsightRowById(id) {
         if (!this.db)
             return null;
@@ -837,27 +894,17 @@ export class DreamEngine {
     // Branch Management (ADR-069)
     // ==========================================================================
     /**
-     * Get the RVCOW branch manager, if branching is enabled.
+     * @deprecated #1060: branching is ignored; always null.
      */
     getBranchManager() {
-        return this.branchManager;
+        return null;
     }
     /**
-     * Register a listener for branch lifecycle events.
+     * @deprecated #1060: branching is ignored, so no branch event is emitted.
      */
     onBranchEvent(listener) {
         this.branchEventListeners.push(listener);
     }
-    emitBranchEvent(event, branch, detail) {
-        for (const listener of this.branchEventListeners) {
-            try {
-                listener(event, branch, detail);
-            }
-            catch {
-                // Swallow listener errors
-            }
-        }
-    }
     // ==========================================================================
     // Cleanup
     // ==========================================================================
@@ -865,17 +912,27 @@ export class DreamEngine {
      * Release resources (does NOT close the shared database)
      */
     async close() {
-        // #1060: a dream still in flight is recorded as interrupted before the
-        // engine lets go of the database.
+        // #1060: stop a dream still in flight and record it as interrupted, then
+        // wait (briefly) for it to unwind before letting go of the database.
+        // A close counts as a cancel, so a caller running several dreams in a row
+        // (SpeculativeDreamer) stops instead of committing an earlier result.
+        this.closing = true;
+        this.cancelRequests++;
         this.interruptActiveDream?.();
         this.interruptActiveDream = null;
+        this.activeAbort?.abort();
+        const inFlight = this.activeDream?.done;
+        if (inFlight) {
+            let timer;
+            await Promise.race([inFlight, new Promise((resolve) => { timer = setTimeout(resolve, 2000); })]);
+            clearTimeout(timer);
+        }
         if (this.graph) {
             await this.graph.close();
             this.graph = null;
         }
         this.db = null;
         this.persistence = null;
-        this.branchManager = null;
         this.initialized = false;
         this.currentCycle = null;
     }

package/dist/learning/dream/dream-insights-pruner.d.ts

@@ -14,10 +14,18 @@
  * `getPendingInsights` target and vector embeddings (if attached) grow
  * unbounded.
  *
- * Strategy: delete only insights that:
+ * Strategy: move out of `dream_insights` only insights that:
  *   - have never been applied (`applied = 0`), AND
  *   - are older than the retention window (default 30 days)
  *
+ * #1066: rows are archived, not lost. In one write transaction (BEGIN
+ * IMMEDIATE, so it waits on busy_timeout instead of failing on lock upgrade)
+ * each qualifying row is copied to `dream_insights_archive`, the copies are
+ * read back, and only rows whose copy is present are deleted. If the
+ * read-back does not match, the transaction rolls back and nothing is
+ * deleted. The archive has its own key, so an insight swept twice keeps both
+ * copies.
+ *
  * Applied insights stay forever — they're part of the audit trail for
  * pattern changes. Recently-created insights stay regardless of applied
  * state — they might still be picked up by a future `applyInsight` pass.
@@ -27,6 +35,7 @@
  * with the rest of its lifecycle work.
  */
 import type { Database as DatabaseType } from 'better-sqlite3';
+import { DREAM_INSIGHTS_ARCHIVE_TABLE } from '../../migrations/20261018_add_dream_insights_archive.js';
 export interface PruneStaleDreamInsightsOptions {
     /**
      * How many days old an `applied = 0` insight must be before it's
@@ -38,12 +47,23 @@ export interface PruneStaleDreamInsightsOptions {
 export interface PruneResult {
     /** Number of rows deleted. Zero if the table is empty or no rows qualify. */
     pruned: number;
+    /** Number of rows copied to `dream_insights_archive` before the delete. */
+    archived: number;
+    /**
+     * #1116: stale rows left in place because their `id` is NULL. The archive
+     * needs an id (NOT NULL) and the delete matches on it, so such a row can be
+     * neither copied nor removed safely; before #1116 it made every sweep fail.
+     */
+    skippedNullId: number;
 }
+export { DREAM_INSIGHTS_ARCHIVE_TABLE };
 /**
- * Delete stale unapplied insights. Idempotent — safe to call on every tick.
+ * Archive, then delete, stale unapplied insights. Idempotent — safe to call
+ * on every tick.
  *
- * Returns `{ pruned: 0 }` if the table doesn't exist (init hasn't created
- * the dream schema yet) or if no rows qualify.
+ * Returns `{ pruned: 0, archived: 0, skippedNullId: 0 }` if the table doesn't exist (init hasn't
+ * created the dream schema yet) or if no rows qualify. Throws, with nothing
+ * deleted, if the archive copy cannot be verified.
  */
 export declare function pruneStaleDreamInsights(db: DatabaseType, options?: PruneStaleDreamInsightsOptions): PruneResult;
 //# sourceMappingURL=dream-insights-pruner.d.ts.map