agentic-qe 3.15.12 → 3.15.14

package/dist/integrations/ruvector/brain-rvf-exporter.js

@@ -9,6 +9,54 @@ import { createRvfStore, openRvfStore, openRvfStoreReadonly, isRvfNativeAvailabl
 import { sha256, tableExists, queryAll, domainFilterForColumn, runImportTransaction, mergeGenericRow, remapPatternReferences, mergeAppendOnlyRow, TABLE_CONFIGS, TABLE_BLOB_COLUMNS, PK_COLUMNS, CONFIDENCE_COLUMNS, TIMESTAMP_COLUMNS, serializeRowBlobs, deserializeRowBlobs, } from './brain-shared.js';
 import { appendBrainImportWitness } from './brain-import-audit.js';
 // --- Export ---
+/**
+ * Largest kernel image @ruvector/rvf-node accepts. One byte more and
+ * `embedKernel` fails with a misleading `RVF error 0x0303: FsyncFailed`
+ * (#1238; measured 134,217,728 B ok, 134,217,729 B fails).
+ */
+export const RVF_MAX_KERNEL_BYTES = 128 * 1024 * 1024;
+/**
+ * Vector ids written by the code-intelligence domain (KG nodes, semantic code
+ * index, C4 diagrams). They are derived from source code and rebuilt by
+ * `aqe code index`, so they stay out of the brain kernel (#1238).
+ */
+export const CODE_INDEX_VECTOR_ID_PREFIX = 'code-intelligence:';
+const CODE_INDEX_VECTOR_MATCH = `substr(id, 1, ${CODE_INDEX_VECTOR_ID_PREFIX.length}) = ?`;
+function isCodeIndexVectorRow(tableName, row) {
+    if (tableName !== 'vectors')
+        return false;
+    const id = row.id;
+    return typeof id === 'string' && id.startsWith(CODE_INDEX_VECTOR_ID_PREFIX);
+}
+/** Thrown before any native call when the kernel would exceed the RVF limit. */
+export class RvfKernelTooLargeError extends Error {
+    kernelBytes;
+    limitBytes;
+    tableBytes;
+    complete;
+    code = 'RVF_KERNEL_TOO_LARGE';
+    constructor(kernelBytes, limitBytes, tableBytes, complete) {
+        const largest = Object.entries(tableBytes)
+            .filter(([, bytes]) => bytes >= 1024 * 1024)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 3)
+            .map(([table, bytes]) => `${table} ${formatMb(bytes)}`)
+            .join(', ');
+        super(`RVF_KERNEL_TOO_LARGE: the brain kernel needs ${complete ? '' : 'at least '}` +
+            `${formatMb(kernelBytes)}, over the ${formatMb(limitBytes)} limit of the native RVF writer.` +
+            (largest ? ` Largest tables: ${largest}.` : '') +
+            ' Nothing was written. ' +
+            `Use --format jsonl (no size limit), or reduce the largest learning tables first.`);
+        this.kernelBytes = kernelBytes;
+        this.limitBytes = limitBytes;
+        this.tableBytes = tableBytes;
+        this.complete = complete;
+        this.name = 'RvfKernelTooLargeError';
+    }
+}
+function formatMb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
 /**
  * Sidecar suffixes that make up a complete store on disk. `''` is the store
  * itself; the adapter writes `.idmap.json` on close, and we write the manifest.
@@ -98,52 +146,93 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
     const tmpPath = `${outPath}.tmp.${process.pid}`;
     sweepStaleTmpFiles(outPath);
     removeStoreFiles(tmpPath);
-    // Create RVF container via adapter (handles idmap automatically)
-    const rvf = createRvfStore(tmpPath, dimension);
-    let closed = false;
-    try {
-        // --- Export all tables using TABLE_CONFIGS ---
-        const allTableData = {};
-        const domainSet = new Set();
-        let totalRecords = 0;
-        for (const config of TABLE_CONFIGS) {
-            const [where, params] = config.domainColumn
-                ? domainFilterForColumn(options.domains, config.domainColumn)
-                : [undefined, []];
-            let rows = queryAll(db, config.tableName, where, params);
-            if (options.domains && options.domains.length > 0) {
-                const manifestIds = new Set((allTableData.learning_evidence_manifests ?? []).map(row => row.id));
-                const patternIds = new Set((allTableData.qe_patterns ?? []).map(row => row.id));
-                if (['learning_evidence_segments', 'learning_segment_edges', 'learning_evidence_admissions'].includes(config.tableName)) {
-                    rows = rows.filter(row => manifestIds.has(row.manifest_id));
-                }
-                else if (config.tableName === 'pattern_manifest_lineage') {
-                    rows = rows.filter(row => {
-                        const lineage = row;
-                        return manifestIds.has(lineage.manifest_id) && patternIds.has(lineage.pattern_id);
-                    });
-                }
-                else if (config.tableName === 'pattern_segment_lineage') {
-                    rows = rows.filter(row => {
-                        const lineage = row;
-                        return manifestIds.has(lineage.manifest_id) && patternIds.has(lineage.pattern_id);
-                    });
-                }
+    // --- Serialize all tables using TABLE_CONFIGS, before any native call ---
+    // Issue #1238: the native writer has a hard kernel ceiling, so each table is
+    // serialized once and measured as it goes. An oversized brain fails here,
+    // without creating a store or spending time on the rest of the tables.
+    const maxKernelBytes = options.maxKernelBytes ?? RVF_MAX_KERNEL_BYTES;
+    const allTableData = {};
+    const tableJson = [];
+    const tableBytes = {};
+    const tableCounts = {};
+    const skippedCacheRows = {};
+    const domainSet = new Set();
+    let totalRecords = 0;
+    let kernelBytes = 0;
+    for (const config of TABLE_CONFIGS) {
+        let [where, params] = config.domainColumn
+            ? domainFilterForColumn(options.domains, config.domainColumn)
+            : [undefined, []];
+        if (config.tableName === 'vectors' && tableExists(db, 'vectors')) {
+            const { n } = db.prepare(`SELECT COUNT(*) AS n FROM vectors WHERE ${CODE_INDEX_VECTOR_MATCH}`).get(CODE_INDEX_VECTOR_ID_PREFIX);
+            if (n > 0)
+                skippedCacheRows.vectors = n;
+            where = `(id IS NULL OR NOT ${CODE_INDEX_VECTOR_MATCH})`;
+            params = [CODE_INDEX_VECTOR_ID_PREFIX];
+        }
+        let rows = queryAll(db, config.tableName, where, params);
+        if (options.domains && options.domains.length > 0) {
+            const manifestIds = new Set((allTableData.learning_evidence_manifests ?? []).map(row => row.id));
+            const patternIds = new Set((allTableData.qe_patterns ?? []).map(row => row.id));
+            if (['learning_evidence_segments', 'learning_segment_edges', 'learning_evidence_admissions'].includes(config.tableName)) {
+                rows = rows.filter(row => manifestIds.has(row.manifest_id));
             }
-            if (config.tableName === 'qe_patterns') {
-                for (const p of rows) {
-                    if (p.qe_domain)
-                        domainSet.add(p.qe_domain);
-                }
+            else if (config.tableName === 'pattern_manifest_lineage') {
+                rows = rows.filter(row => {
+                    const lineage = row;
+                    return manifestIds.has(lineage.manifest_id) && patternIds.has(lineage.pattern_id);
+                });
+            }
+            else if (config.tableName === 'pattern_segment_lineage') {
+                rows = rows.filter(row => {
+                    const lineage = row;
+                    return manifestIds.has(lineage.manifest_id) && patternIds.has(lineage.pattern_id);
+                });
             }
-            // Serialize BLOBs to Base64 for JSON storage
-            const blobCols = TABLE_BLOB_COLUMNS[config.tableName];
-            if (blobCols && blobCols.length > 0) {
-                rows = rows.map(r => serializeRowBlobs(r, blobCols));
+        }
+        if (config.tableName === 'qe_patterns') {
+            for (const p of rows) {
+                if (p.qe_domain)
+                    domainSet.add(p.qe_domain);
             }
+        }
+        // Serialize BLOBs to Base64 for JSON storage
+        const blobCols = TABLE_BLOB_COLUMNS[config.tableName];
+        if (blobCols && blobCols.length > 0) {
+            rows = rows.map(r => serializeRowBlobs(r, blobCols));
+        }
+        // Only these two tables are read back (domain-filtered lineage above).
+        if (config.tableName === 'qe_patterns' || config.tableName === 'learning_evidence_manifests') {
             allTableData[config.tableName] = rows;
-            totalRecords += rows.length;
         }
+        tableCounts[config.tableName] = rows.length;
+        totalRecords += rows.length;
+        const json = JSON.stringify(rows);
+        tableJson.push([config.tableName, json]);
+        tableBytes[config.tableName] = Buffer.byteLength(json);
+        kernelBytes += tableBytes[config.tableName];
+        if (kernelBytes > maxKernelBytes) {
+            throw new RvfKernelTooLargeError(kernelBytes, maxKernelBytes, tableBytes, false);
+        }
+    }
+    // Same bytes JSON.stringify would produce for { version, format, exportedAt,
+    // sourceDb, domains, tables }, assembled from the per-table JSON above.
+    const exportedAt = new Date().toISOString();
+    const domains = [...domainSet].sort();
+    const brainJson = `{"version":"3.0","format":"rvf","exportedAt":${JSON.stringify(exportedAt)},` +
+        `"sourceDb":${JSON.stringify(sourceDbLabel)},"domains":${JSON.stringify(domains)},"tables":{` +
+        tableJson.map(([tableName, json]) => `${JSON.stringify(tableName)}:${json}`).join(',') +
+        '}}';
+    tableJson.length = 0;
+    const kernelBuffer = Buffer.from(brainJson);
+    if (kernelBuffer.length > maxKernelBytes) {
+        throw new RvfKernelTooLargeError(kernelBuffer.length, maxKernelBytes, tableBytes, true);
+    }
+    const checksum = sha256(brainJson);
+    // Create RVF container via adapter (handles idmap automatically)
+    const rvf = createRvfStore(tmpPath, dimension);
+    let closed = false;
+    try {
         // --- Ingest vector embeddings into HNSW ---
         let embeddingCount = 0;
         const embeddingEntries = [];
@@ -175,17 +264,6 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
             embeddingCount = result.accepted;
         }
         // --- Embed full brain data as kernel ---
-        const brainData = {
-            version: '3.0',
-            format: 'rvf',
-            exportedAt: new Date().toISOString(),
-            sourceDb: sourceDbLabel,
-            domains: [...domainSet].sort(),
-            tables: allTableData,
-        };
-        const brainJson = JSON.stringify(brainData);
-        const checksum = sha256(brainJson);
-        const kernelBuffer = Buffer.from(brainJson);
         rvf.embedKernel(kernelBuffer);
         // Optional Ed25519 signing
         const signature = options.sign ? rvf.sign(kernelBuffer) ?? undefined : undefined;
@@ -199,18 +277,19 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
         const manifest = {
             version: '3.0',
             format: 'rvf',
-            exportedAt: brainData.exportedAt,
+            exportedAt,
             sourceDb: sourceDbLabel,
             stats: {
-                patternCount: (allTableData['qe_patterns'] || []).length,
+                patternCount: tableCounts['qe_patterns'] ?? 0,
                 embeddingCount,
-                qValueCount: (allTableData['rl_q_values'] || []).length,
-                dreamInsightCount: (allTableData['dream_insights'] || []).length,
-                witnessChainLength: (allTableData['witness_chain'] || []).length,
+                qValueCount: tableCounts['rl_q_values'] ?? 0,
+                dreamInsightCount: tableCounts['dream_insights'] ?? 0,
+                witnessChainLength: tableCounts['witness_chain'] ?? 0,
                 totalRecords,
-                tableCounts: Object.fromEntries(TABLE_CONFIGS.map(({ tableName }) => [tableName, allTableData[tableName]?.length ?? 0])),
+                tableCounts,
+                ...(Object.keys(skippedCacheRows).length > 0 ? { skippedCacheRows } : {}),
             },
-            domains: brainData.domains,
+            domains,
             checksum,
             rvfStatus: {
                 totalVectors: status.totalVectors,
@@ -243,7 +322,9 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
         if (existsSync(outPath) && !options.allowOverwriteRicher) {
             let existing;
             try {
-                existing = brainInfoFromRvf(outPath);
+                // Code-index vectors are no longer exported (#1238), so an older mirror
+                // that still holds them is compared on the rows both exports carry.
+                existing = readBrainInfo(outPath, true);
             }
             catch (error) {
                 if (hasReadableBrainKernel(outPath) || !isKnownUnusableRvfError(error)) {
@@ -468,6 +549,13 @@ export function importBrainFromRvf(db, rvfPath, options) {
 // --- Info ---
 /** Read brain info from an RVF file without importing. */
 export function brainInfoFromRvf(rvfPath) {
+    return readBrainInfo(rvfPath, false);
+}
+/**
+ * `excludeCodeIndex` drops code-index vector rows from `tableCounts`, which
+ * makes them comparable with the counts of a current export.
+ */
+function readBrainInfo(rvfPath, excludeCodeIndex) {
     if (!isRvfNativeAvailable()) {
         throw new Error('@ruvector/rvf-node is not available.');
     }
@@ -499,7 +587,12 @@ export function brainInfoFromRvf(rvfPath) {
         const tableCounts = t && typeof t === 'object' && !Array.isArray(t)
             ? Object.fromEntries(Object.entries(t)
                 .filter((entry) => Array.isArray(entry[1]))
-                .map(([tableName, rows]) => [tableName, rows.length]))
+                .map(([tableName, rows]) => [
+                tableName,
+                excludeCodeIndex
+                    ? rows.filter(row => !isCodeIndexVectorRow(tableName, row)).length
+                    : rows.length,
+            ]))
             : undefined;
         return {
             version: '3.0',

package/dist/integrations/ruvector/transfer-coherence-stub.js

@@ -11,9 +11,11 @@
  *
  * @module integrations/ruvector/transfer-coherence-stub
  */
-import { createRequire } from 'module';
 import { getRuVectorFeatureFlags } from './feature-flags.js';
-const esmRequire = createRequire(import.meta.url);
+// Static import so the bundlers inline the gate. A runtime
+// require('./coherence-gate.js') resolves against the bundle file instead,
+// fails, and silently returned the approve-everything stub (#1237).
+import { CoherenceGate } from './coherence-gate-core.js';
 // ============================================================================
 // Stub Implementation
 // ============================================================================
@@ -49,14 +51,7 @@ export class TransferCoherenceStub {
  */
 export function createTransferCoherenceGate() {
     if (getRuVectorFeatureFlags().useCoherenceGate) {
-        try {
-            // Dynamic require to avoid circular dependency at module level
-            const { CoherenceGate } = esmRequire('./coherence-gate.js');
-            return new CoherenceGate();
-        }
-        catch {
-            // Fall through to stub if CoherenceGate fails to load
-        }
+        return new CoherenceGate();
     }
     return new TransferCoherenceStub();
 }

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

@@ -14,11 +14,18 @@
  *
  * @module learning/dream/dream-engine
  */
+/**
+ * #1239: how long retention waits for a locked database. better-sqlite3 waits
+ * synchronously, and retention is optional (the next dream retries), so it
+ * gives up quickly instead of using the engine's 60 s commit wait.
+ */
+export declare const RETENTION_BUSY_TIMEOUT_MS = 1000;
 import { type ActivationConfig } from './spreading-activation.js';
 import { type InsightConfig, type DreamInsight } from './insight-generator.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 DreamRetentionReport } from '../learning-retention.js';
 import type { DreamCycle, PatternImportData, FailureImportData, SuccessImportData } from './types.js';
 /**
  * Complete DreamEngine configuration
@@ -66,6 +73,12 @@ export interface DreamCycleResult {
     patternsCreated: number;
     /** #1060: how long the single commit transaction held the write lock, in ms. */
     commitDurationMs?: number;
+    /**
+     * #1239: dream retention after the commit, with row counts. Off by default
+     * (AQE_DREAM_RETENTION); while off, the steps are a dry run showing what
+     * they would remove.
+     */
+    retention?: DreamRetentionReport;
     /**
      * #1060: the uncommitted results of a `dream(…, { commit: false })` run.
      * Pass the result to DreamEngine.commitDreamResult() to write them.
@@ -202,8 +215,18 @@ export declare class DreamEngine {
      * fails.
      */
     commitDreamResult(result: DreamCycleResult): number;
-    /** Commit a computed dream, then record it in the witness chain (#1060). */
+    /**
+     * Commit a computed dream, then record it in the witness chain (#1060) and
+     * run the default retention steps (#1239).
+     */
     private commitComputed;
+    /**
+     * #1239: after a committed dream, drop failed cycles past their retention
+     * window and outcome concepts beyond the cap when AQE_DREAM_RETENTION=on;
+     * otherwise only count what that would remove. The dream is already
+     * committed, so a failure here (a locked database, say) is only logged.
+     */
+    private runDefaultRetention;
     /**
      * #1060: build a synchronous handler that stops a still-running dream and
      * records its cycle as 'interrupted'. It runs from close() and from a

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

@@ -19,6 +19,14 @@ import { toErrorMessage } from '../../shared/error-utils.js';
 import { PatternMutationError } from '../pattern-mutation-error.js';
 import { LoggerFactory } from '../../logging/index.js';
 const dreamLogger = LoggerFactory.create('dream-engine');
+/** #1239: an unreadable retention setting is reported once per process. */
+let retentionWarningsLogged = false;
+/**
+ * #1239: how long retention waits for a locked database. better-sqlite3 waits
+ * synchronously, and retention is optional (the next dream retries), so it
+ * gives up quickly instead of using the engine's 60 s commit wait.
+ */
+export const RETENTION_BUSY_TIMEOUT_MS = 1000;
 import { v4 as uuidv4 } from 'uuid';
 import { getUnifiedPersistence } from '../../kernel/unified-persistence.js';
 import { registerStoreCloser } from '../../kernel/process-lifecycle.js';
@@ -27,6 +35,7 @@ import { SpreadingActivation, } from './spreading-activation.js';
 import { InsightGenerator, } from './insight-generator.js';
 import { DEFAULT_VALIDATION_THRESHOLDS, } from './rvcow-branch-manager.js';
 import { commitDream, markAbandonedCycles, ABANDONED_CYCLE_GRACE_MS, } from './dream-commit.js';
+import { describeRetention, resolveDefaultRetention, runDreamRetention, } from '../learning-retention.js';
 /**
  * Default DreamEngine configuration
  */
@@ -474,8 +483,10 @@ export class DreamEngine {
                 committed = true; // nothing to record: the caller decides
                 return { ...result, pending: computed };
             }
-            result.commitDurationMs = this.commitComputed(db, computed);
+            const commit = this.commitComputed(db, computed);
             committed = true;
+            result.commitDurationMs = commit.durationMs;
+            result.retention = commit.retention;
             return result;
         }
         catch (error) {
@@ -527,12 +538,16 @@ export class DreamEngine {
         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);
+        const commit = this.commitComputed(this.db, result.pending);
         result.pending = undefined;
-        result.commitDurationMs = duration;
-        return duration;
+        result.commitDurationMs = commit.durationMs;
+        result.retention = commit.retention;
+        return commit.durationMs;
     }
-    /** Commit a computed dream, then record it in the witness chain (#1060). */
+    /**
+     * Commit a computed dream, then record it in the witness chain (#1060) and
+     * run the default retention steps (#1239).
+     */
     commitComputed(db, computed) {
         const commit = commitDream(db, computed);
         try {
@@ -544,7 +559,43 @@ export class DreamEngine {
             }, 'dream-engine');
         }
         catch { /* best-effort witness */ }
-        return commit.commitDurationMs;
+        return { durationMs: commit.commitDurationMs, retention: this.runDefaultRetention(db) };
+    }
+    /**
+     * #1239: after a committed dream, drop failed cycles past their retention
+     * window and outcome concepts beyond the cap when AQE_DREAM_RETENTION=on;
+     * otherwise only count what that would remove. The dream is already
+     * committed, so a failure here (a locked database, say) is only logged.
+     */
+    runDefaultRetention(db) {
+        const settings = resolveDefaultRetention();
+        if (settings.warnings.length > 0 && !retentionWarningsLogged) {
+            retentionWarningsLogged = true;
+            for (const warning of settings.warnings)
+                dreamLogger.warn(warning);
+        }
+        const previousBusyTimeout = db.pragma('busy_timeout', { simple: true });
+        try {
+            db.pragma(`busy_timeout = ${RETENTION_BUSY_TIMEOUT_MS}`);
+            const report = runDreamRetention(db, settings);
+            if (report.enabled) {
+                for (const step of report.steps) {
+                    if (step.affected > 0)
+                        dreamLogger.info(`Retention ${describeRetention(step)}`);
+                }
+            }
+            return report;
+        }
+        catch (error) {
+            dreamLogger.warn('Dream retention skipped after dream commit', { error: toErrorMessage(error) });
+            return { enabled: settings.enabled, steps: [], error: toErrorMessage(error) };
+        }
+        finally {
+            try {
+                db.pragma(`busy_timeout = ${previousBusyTimeout}`);
+            }
+            catch { /* connection gone */ }
+        }
     }
     /**
      * #1060: build a synchronous handler that stops a still-running dream and

package/dist/learning/learning-retention.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Learning Retention (#1239)
+ *
+ * Bounds the learning tables that otherwise grow for as long as a project
+ * lives. Two kinds of step, kept apart on purpose:
+ *
+ * - Dream retention steps remove only rows that carry no learning value.
+ *   They are off by default. With `AQE_DREAM_RETENTION=on` they run after
+ *   each committed dream cycle; while off, the dream reports what they
+ *   would remove (COUNT queries only, nothing is written):
+ *     - failed/interrupted `dream_cycles` past a retention window. A cycle
+ *       that did not commit wrote no insights, and any cycle that still has
+ *       an insight is kept.
+ *     - `outcome` concept nodes beyond a cap, with their edges. They are
+ *       derived from `qe_pattern_usage`, which is not touched, and only the
+ *       newest 100 usage rows are ever loaded back, so a cap >= 100 does not
+ *       churn.
+ *
+ * - Opt-in steps drop data that could still matter to someone, so they run
+ *   only from `aqe learning prune`, which defaults to a dry run:
+ *     - compacting soft-archived and merged experiences: `result_json` and the
+ *       embedding are cleared, the row and its counters stay (the experience
+ *       count stays monotonic, v3.9.22).
+ *     - `routing_outcomes` older than a number of days.
+ *
+ * Every step reports the row counts it measured before and after, or, in a
+ * dry run, the counts it would change.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+export interface TableCount {
+    readonly table: string;
+    readonly before: number;
+    readonly after: number;
+}
+export interface RetentionStepResult {
+    readonly step: RetentionStep;
+    readonly dryRun: boolean;
+    /** Rows deleted, or for compaction rows whose payload was cleared. */
+    readonly affected: number;
+    /**
+     * Row counts per table. `after` is read back after the write; in a dry run
+     * it is the projection (`before` minus the rows the step would delete).
+     */
+    readonly tables: readonly TableCount[];
+    /** Bytes of payload removed (compaction only), measured with length(). */
+    readonly payloadBytes?: number;
+}
+export type RetentionStep = 'failed-dream-cycles' | 'outcome-concepts' | 'compact-experiences' | 'routing-outcomes';
+export declare const DEFAULT_FAILED_DREAM_CYCLE_RETENTION_DAYS = 7;
+export declare const DEFAULT_OUTCOME_CONCEPT_CAP = 2000;
+/** Below this the cap would delete outcome nodes that the next dream reloads. */
+export declare const MIN_OUTCOME_CONCEPT_CAP = 100;
+/** Failed or interrupted cycles older than `retentionDays` that have no insight. */
+export declare function pruneFailedDreamCycles(db: DatabaseType, options?: {
+    retentionDays?: number;
+    dryRun?: boolean;
+}): RetentionStepResult;
+/** Keep the newest `maxNodes` outcome concept nodes; delete the rest and their edges. */
+export declare function capOutcomeConcepts(db: DatabaseType, options?: {
+    maxNodes?: number;
+    dryRun?: boolean;
+}): RetentionStepResult;
+/** Clear `result_json` and the embedding of archived and merged experiences. */
+export declare function compactConsolidatedExperiences(db: DatabaseType, options?: {
+    dryRun?: boolean;
+}): RetentionStepResult;
+/** Delete routing outcomes older than `olderThanDays`. */
+export declare function pruneRoutingOutcomes(db: DatabaseType, options: {
+    olderThanDays: number;
+    dryRun?: boolean;
+}): RetentionStepResult;
+export interface DefaultRetentionSettings {
+    /** AQE_DREAM_RETENTION: false (the default) previews the steps instead of running them. */
+    readonly enabled: boolean;
+    /** null = off */
+    readonly failedDreamCycleRetentionDays: number | null;
+    /** null = off */
+    readonly outcomeConceptCap: number | null;
+    readonly warnings: readonly string[];
+}
+/**
+ * Read `AQE_DREAM_RETENTION` (off by default) and the per-step settings
+ * `AQE_FAILED_DREAM_CYCLE_RETENTION_DAYS` (default 7) and
+ * `AQE_OUTCOME_CONCEPT_CAP` (default 2000). Each step setting accepts "off".
+ */
+export declare function resolveDefaultRetention(env?: Readonly<Record<string, string | undefined>>): DefaultRetentionSettings;
+export interface DreamRetentionReport {
+    /** False: the steps ran as a dry run and wrote nothing. */
+    readonly enabled: boolean;
+    readonly steps: readonly RetentionStepResult[];
+    /** Set when retention could not run (a locked database, say); nothing was deleted. */
+    readonly error?: string;
+}
+/**
+ * The dream retention steps that are not switched off individually: run
+ * when retention is enabled, otherwise previewed as a dry run.
+ */
+export declare function runDreamRetention(db: DatabaseType, settings?: DefaultRetentionSettings): DreamRetentionReport;
+/** Lines for a dream's output: what retention removed, or would remove while off. */
+export declare function describeDreamRetention(report: DreamRetentionReport): string[];
+/** One line per step, for logs: "outcome-concepts: 3000 removed (concept_nodes 5000 -> 2000, ...)". */
+export declare function describeRetention(result: RetentionStepResult): string;
+//# sourceMappingURL=learning-retention.d.ts.map