agentic-qe 3.15.8 → 3.15.10

package/dist/learning/dream/dream-engine.d.ts

@@ -16,7 +16,8 @@
  */
 import { type ActivationConfig } from './spreading-activation.js';
 import { type InsightConfig, type DreamInsight } from './insight-generator.js';
-import { RVCOWBranchManager, type Branch, type ValidationResult, type ValidationThresholds } from './rvcow-branch-manager.js';
+import { type Branch, type ValidationResult, type ValidationThresholds } from './rvcow-branch-manager.js';
+import { type ComputedDream } from './dream-commit.js';
 import type { WitnessChain } from '../../audit/witness-chain.js';
 import type { DreamCycle, PatternImportData, FailureImportData, SuccessImportData } from './types.js';
 /**
@@ -32,19 +33,12 @@ export interface DreamConfig {
     /** Insight generation configuration */
     insightConfig: InsightConfig;
     /**
-     * Enable RVCOW branching for reversible dream cycles (ADR-069).
-     * Default: false (#1060).
-     *
-     * RISK — opt in only for an isolated database connection. The branch is a
-     * SQLite SAVEPOINT on the process-wide shared connection, and it stays open
-     * for the whole asynchronous dream (up to `maxDurationMs`). Every other
-     * write made on that connection in the meantime (memory_store, pattern
-     * updates, experience capture) joins the savepoint. A discard (failed
-     * validation, error, cancel) rolls those foreground writes back even though
-     * they were already acknowledged. Branch validation only inspects
-     * `qe_patterns`, which `dream()` does not write, so branching adds little
-     * protection to a dream cycle. A compute-then-commit rework is tracked in
-     * #1060.
+     * @deprecated #1060: ignored. A dream is computed in memory and its results
+     * are committed in one short synchronous transaction (see dream-commit.ts),
+     * which gives the atomicity branching was meant to provide without holding
+     * a SAVEPOINT on the shared connection across the asynchronous dream (that
+     * rolled back acknowledged foreground writes). Setting it to true logs a
+     * warning and has no other effect. Kept so existing configs still load.
      */
     enableBranching: boolean;
     /** Validation thresholds for dream branch quality checks */
@@ -70,6 +64,30 @@ export interface DreamCycleResult {
     };
     /** Number of patterns created from insights */
     patternsCreated: number;
+    /** #1060: how long the single commit transaction held the write lock, in ms. */
+    commitDurationMs?: number;
+    /**
+     * #1060: the uncommitted results of a `dream(…, { commit: false })` run.
+     * Pass the result to DreamEngine.commitDreamResult() to write them.
+     */
+    pending?: ComputedDream;
+}
+/** #1060: per-call options for DreamEngine.dream(). */
+export interface DreamRunOptions {
+    /** Minimum concepts required for this run (default: config.minConceptsRequired). */
+    minConceptsRequired?: number;
+    /** Activation parameter overrides for this run (SpeculativeDreamer strategies). */
+    activationConfig?: Partial<ActivationConfig>;
+    /**
+     * Write the results (default true). With false the dream writes nothing at
+     * all, not even its cycle row, and returns them in `pending`.
+     */
+    commit?: boolean;
+}
+/** #1060: a second dream on the same engine while one is running. */
+export declare class DreamAlreadyRunningError extends Error {
+    readonly cycleId: string;
+    constructor(cycleId: string);
 }
 /**
  * Result of applying an insight
@@ -117,19 +135,25 @@ export declare class DreamEngine {
     private persistence;
     private graph;
     private db;
-    private branchManager;
     /** #1060: marks the in-flight dream cycle interrupted (set while dreaming). */
     private interruptActiveDream;
+    /** #1060: the in-flight dream, so close() can wait for it to stop. */
+    private activeDream;
+    /** #1060: stops the in-flight dream's activation loop. */
+    private activeAbort;
     private currentCycle;
     private initialized;
     private cancelled;
+    /** #1060: how many times cancelDream() was called (see cancelCount). */
+    private cancelRequests;
+    /** #1060: set by close() until the engine is initialized again. */
+    private closing;
     private branchEventListeners;
     /** Optional witness chain for audit trail of dream decisions (ADR-070) */
     private _witnessChain;
     set witnessChain(wc: WitnessChain | null);
-    /** Optional RVF adapter for COW branching (ADR-069). Set externally to share with PatternStore. */
-    private _rvfAdapter;
-    set rvfAdapter(adapter: any);
+    /** @deprecated #1060: branching is ignored, so the RVF adapter is unused. */
+    set rvfAdapter(_adapter: any);
     constructor(config?: Partial<DreamConfig>);
     /**
      * Initialize using unified persistence
@@ -150,17 +174,41 @@ export declare 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
      */
-    dream(durationMs?: number): Promise<DreamCycleResult>;
+    dream(durationMs?: number, options?: DreamRunOptions): Promise<DreamCycleResult>;
+    /**
+     * #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.
+     */
+    private runDream;
     /**
-     * #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: 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: DreamCycleResult): number;
+    /** Commit a computed dream, then record it in the witness chain (#1060). */
+    private commitComputed;
+    /**
+     * #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.
      */
     private createCycleInterrupter;
     /**
@@ -214,6 +262,11 @@ export declare class DreamEngine {
      * @returns Array of dream cycles
      */
     getDreamHistory(limit?: number): Promise<DreamCycle[]>;
+    /**
+     * #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(): number;
     /**
      * Cancel the running dream cycle.
      */
@@ -227,19 +280,16 @@ export declare class DreamEngine {
      */
     getCurrentCycle(): DreamCycle | null;
     private saveCycle;
-    private updateCycle;
     private updateCycleSync;
-    private saveInsight;
     private getInsightRowById;
     /**
-     * Get the RVCOW branch manager, if branching is enabled.
+     * @deprecated #1060: branching is ignored; always null.
      */
-    getBranchManager(): RVCOWBranchManager | null;
+    getBranchManager(): null;
     /**
-     * Register a listener for branch lifecycle events.
+     * @deprecated #1060: branching is ignored, so no branch event is emitted.
      */
     onBranchEvent(listener: (event: string, branch: Branch, detail?: ValidationResult) => void): void;
-    private emitBranchEvent;
     /**
      * Release resources (does NOT close the shared database)
      */