audrey 0.20.0 → 0.23.1

package/dist/src/audrey.js

@@ -9,6 +9,8 @@ import { runConsolidation } from './consolidate.js';
 import { applyDecay } from './decay.js';
 import { rollbackConsolidation, getConsolidationHistory } from './rollback.js';
 import { forgetMemory, forgetByQuery as forgetByQueryFn, purgeMemories } from './forget.js';
+import { applyFeedback } from './feedback.js';
+import { buildImpactReport } from './impact.js';
 import { introspect as introspectFn } from './introspect.js';
 import { buildContextResolutionPrompt, buildReflectionPrompt } from './prompts.js';
 import { exportMemories } from './export.js';
@@ -20,11 +22,101 @@ import { detectResonance } from './affect.js';
 import { observeTool } from './tool-trace.js';
 import { listEvents, countEvents, recentFailures, } from './events.js';
 import { buildCapsule } from './capsule.js';
+import { buildPreflight } from './preflight.js';
+import { buildReflexReport } from './reflexes.js';
 import { findPromotionCandidates, } from './promote.js';
 import { renderAllRules } from './rules-compiler.js';
 import { insertEvent } from './events.js';
 import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
-import { dirname, join, resolve as pathResolve } from 'node:path';
+import { dirname, join, resolve as pathResolve, relative, isAbsolute as pathIsAbsolute } from 'node:path';
+import { ProfileRecorder } from './profile.js';
+import { performance } from 'node:perf_hooks';
+function roundMs(value) {
+    return Math.round(value * 1000) / 1000;
+}
+function validateEncodeParams(params) {
+    if (!params.content || typeof params.content !== 'string') {
+        throw new Error('content must be a non-empty string');
+    }
+    if (params.salience !== undefined && (params.salience < 0 || params.salience > 1)) {
+        throw new Error('salience must be between 0 and 1');
+    }
+    if (params.tags !== undefined && !Array.isArray(params.tags)) {
+        throw new Error('tags must be an array');
+    }
+}
+const REFLECTION_SOURCES = new Set([
+    'direct-observation',
+    'told-by-user',
+    'inference',
+]);
+function boundedString(value, maxLength) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.slice(0, maxLength);
+}
+function boundedNumber(value, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return undefined;
+    return Math.max(min, Math.min(max, value));
+}
+function normalizeReflectionAffect(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const record = raw;
+    const valence = boundedNumber(record.valence, -1, 1);
+    const arousal = boundedNumber(record.arousal, 0, 1);
+    if (valence === undefined && arousal === undefined)
+        return undefined;
+    const affect = {};
+    if (valence !== undefined)
+        affect.valence = valence;
+    if (arousal !== undefined)
+        affect.arousal = arousal;
+    const label = boundedString(record.label, 64);
+    if (label)
+        affect.label = label;
+    return affect;
+}
+function normalizeReflectionMemory(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const record = raw;
+    const content = boundedString(record.content, 5000);
+    if (!content)
+        return null;
+    const source = record.source;
+    if (typeof source !== 'string' || !REFLECTION_SOURCES.has(source)) {
+        return null;
+    }
+    const memory = {
+        content,
+        source: source,
+    };
+    const salience = boundedNumber(record.salience, 0, 1);
+    if (salience !== undefined)
+        memory.salience = salience;
+    if (Array.isArray(record.tags)) {
+        const tags = record.tags
+            .map(tag => boundedString(tag, 64))
+            .filter((tag) => Boolean(tag))
+            .slice(0, 20);
+        if (tags.length > 0)
+            memory.tags = tags;
+    }
+    if (typeof record.private === 'boolean')
+        memory.private = record.private;
+    const affect = normalizeReflectionAffect(record.affect);
+    if (affect)
+        memory.affect = affect;
+    return memory;
+}
+function messagesToLegacyPrompt(messages) {
+    return messages.map(message => `${message.role.toUpperCase()}:\n${message.content}`).join('\n\n');
+}
 export class Audrey extends EventEmitter {
     agent;
     dataDir;
@@ -37,10 +129,18 @@ export class Audrey extends EventEmitter {
     interferenceConfig;
     contextConfig;
     affectConfig;
+    defaultRetrievalMode;
     autoReflect;
     _migrationPending;
     _autoConsolidateTimer;
     _closed;
+    _postEncodeQueue;
+    _pendingPostEncodeIds;
+    _embeddingWarm;
+    _embeddingWarmupPromise;
+    _warmupDurationMs;
+    _lastRecallCheckAt;
+    _lastRecallErrors;
     constructor({ dataDir = './audrey-data', agent = 'default', embedding = { provider: 'mock', dimensions: 64 }, llm, confidence = {}, consolidation = {}, decay = {}, interference = {}, context = {}, affect = {}, autoReflect = false, } = {}) {
         super();
         const dormantThreshold = decay.dormantThreshold ?? 0.1;
@@ -67,9 +167,9 @@ export class Audrey extends EventEmitter {
             affectWeight: affect.weight ?? 0.2,
         };
         this.consolidationConfig = {
-            minEpisodes: consolidation.minEpisodes || 3,
+            minEpisodes,
         };
-        this.decayConfig = { dormantThreshold: decay.dormantThreshold || 0.1 };
+        this.decayConfig = { dormantThreshold };
         this._autoConsolidateTimer = null;
         this._closed = false;
         this.interferenceConfig = {
@@ -93,7 +193,15 @@ export class Audrey extends EventEmitter {
                 affectThreshold: affect.resonance?.affectThreshold ?? 0.6,
             },
         };
+        this.defaultRetrievalMode = 'hybrid';
         this.autoReflect = autoReflect;
+        this._postEncodeQueue = Promise.resolve();
+        this._pendingPostEncodeIds = new Set();
+        this._embeddingWarm = false;
+        this._embeddingWarmupPromise = null;
+        this._warmupDurationMs = null;
+        this._lastRecallCheckAt = null;
+        this._lastRecallErrors = [];
     }
     async _ensureMigrated() {
         if (!this._migrationPending)
@@ -102,54 +210,207 @@ export class Audrey extends EventEmitter {
         this._migrationPending = false;
         this.emit('migration', counts);
     }
-    _emitValidation(id, params) {
-        validateMemory(this.db, this.embeddingProvider, { id, ...params }, {
-            llmProvider: this.llmProvider,
+    startEmbeddingWarmup(text = 'warmup') {
+        if (this._embeddingWarm)
+            return Promise.resolve();
+        if (this._embeddingWarmupPromise)
+            return this._embeddingWarmupPromise;
+        const startedAt = performance.now();
+        this._embeddingWarmupPromise = (async () => {
+            if (typeof this.embeddingProvider.ready === 'function') {
+                await this.embeddingProvider.ready();
+            }
+            await this.embeddingProvider.embed(text);
+            this._embeddingWarm = true;
+        })()
+            .catch(err => {
+            this._emitQueueError(err);
+            throw err;
         })
-            .then(validation => {
-            if (validation.action === 'reinforced') {
-                this.emit('reinforcement', {
-                    episodeId: id,
-                    targetId: validation.semanticId,
-                    similarity: validation.similarity,
-                });
+            .finally(() => {
+            this._warmupDurationMs = roundMs(performance.now() - startedAt);
+        });
+        return this._embeddingWarmupPromise;
+    }
+    async _waitForEmbeddingWarmup(profile, spanName = 'embedding.wait_for_warmup') {
+        if (!this._embeddingWarmupPromise || this._embeddingWarm)
+            return;
+        const wait = async () => {
+            try {
+                await this._embeddingWarmupPromise;
             }
-            else if (validation.action === 'contradiction') {
-                this.emit('contradiction', {
-                    episodeId: id,
-                    contradictionId: validation.contradictionId,
-                    semanticId: validation.semanticId,
-                    similarity: validation.similarity,
-                    resolution: validation.resolution,
-                });
+            catch {
+                // Warmup failure should not poison the foreground call; the foreground
+                // embed path will surface provider errors if the provider is truly broken.
             }
-        })
-            .catch(err => this.emit('error', err));
+        };
+        if (profile)
+            await profile.measure(spanName, wait);
+        else
+            await wait();
     }
-    async encode(params) {
-        await this._ensureMigrated();
-        const encodeParams = { ...params, arousalWeight: this.affectConfig.arousalWeight };
-        const id = await encodeEpisode(this.db, this.embeddingProvider, encodeParams);
-        this.emit('encode', { id, ...params });
+    async _validateEncodedMemory(id, params, embedding) {
+        const validation = await validateMemory(this.db, this.embeddingProvider, { id, ...params }, {
+            llmProvider: this.llmProvider,
+            embeddingVector: embedding?.vector,
+            embeddingBuffer: embedding?.buffer,
+        });
+        if (validation.action === 'reinforced') {
+            this.emit('reinforcement', {
+                episodeId: id,
+                targetId: validation.semanticId,
+                similarity: validation.similarity,
+            });
+        }
+        else if (validation.action === 'contradiction') {
+            this.emit('contradiction', {
+                episodeId: id,
+                contradictionId: validation.contradictionId,
+                semanticId: validation.semanticId,
+                similarity: validation.similarity,
+                resolution: validation.resolution,
+            });
+        }
+    }
+    async _runPostEncodeStage(name, run) {
+        try {
+            await run();
+        }
+        catch (err) {
+            this._emitQueueError(Object.assign(err instanceof Error ? err : new Error(String(err)), {
+                stage: name,
+            }));
+        }
+    }
+    async _runPostEncode(id, params, embedding) {
         if (this.interferenceConfig.enabled) {
-            applyInterference(this.db, this.embeddingProvider, id, params, this.interferenceConfig)
-                .then(affected => {
+            await this._runPostEncodeStage('interference', async () => {
+                const affected = await applyInterference(this.db, this.embeddingProvider, id, params, this.interferenceConfig, embedding);
                 if (affected.length > 0) {
                     this.emit('interference', { episodeId: id, affected });
                 }
-            })
-                .catch(err => this.emit('error', err));
+            });
         }
         if (this.affectConfig.enabled && this.affectConfig.resonance.enabled && params.affect?.valence !== undefined) {
-            detectResonance(this.db, this.embeddingProvider, id, params, this.affectConfig.resonance)
-                .then(echoes => {
+            await this._runPostEncodeStage('resonance', async () => {
+                const echoes = await detectResonance(this.db, this.embeddingProvider, id, params, this.affectConfig.resonance, embedding);
                 if (echoes.length > 0) {
                     this.emit('resonance', { episodeId: id, affect: params.affect, echoes });
                 }
-            })
-                .catch(err => this.emit('error', err));
+            });
+        }
+        await this._runPostEncodeStage('validation', async () => {
+            await this._validateEncodedMemory(id, params, embedding);
+        });
+    }
+    _enqueuePostEncode(id, params, embedding) {
+        const enqueuedAt = performance.now();
+        this._pendingPostEncodeIds.add(id);
+        const run = async () => {
+            const startedAt = performance.now();
+            try {
+                if (!this._closed) {
+                    await this._runPostEncode(id, params, embedding);
+                }
+            }
+            finally {
+                const finishedAt = performance.now();
+                this._pendingPostEncodeIds.delete(id);
+                this.emit('post-encode-complete', {
+                    episodeId: id,
+                    queued_ms: roundMs(startedAt - enqueuedAt),
+                    processing_ms: roundMs(finishedAt - startedAt),
+                    total_ms: roundMs(finishedAt - enqueuedAt),
+                    pending_consolidation_count: this._pendingPostEncodeIds.size,
+                });
+            }
+        };
+        const task = this._postEncodeQueue.then(run, run);
+        this._postEncodeQueue = task.catch(err => {
+            this._emitQueueError(err);
+        });
+        return task;
+    }
+    _emitQueueError(err) {
+        if (this.listenerCount('error') > 0) {
+            // Caller has opted into error handling; let them route logging.
+            this.emit('error', err);
+            return;
+        }
+        // Standard EventEmitter idiom: log only when nobody is listening, so we
+        // surface failures by default but don't double-log for apps with structured
+        // error pipelines. The MCP server registers a logger listener at startup.
+        const stage = err?.stage;
+        const prefix = stage ? `[audrey:post-encode:${stage}]` : '[audrey:post-encode]';
+        const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+        console.error(`${prefix} ${message}`);
+    }
+    pendingConsolidationIds() {
+        return [...this._pendingPostEncodeIds];
+    }
+    async drainPostEncodeQueue(timeoutMs = 5000) {
+        if (this._pendingPostEncodeIds.size === 0) {
+            return { drained: true, pendingIds: [] };
+        }
+        let timeout;
+        const timedOut = Symbol('timed-out');
+        const timeoutPromise = new Promise(resolve => {
+            timeout = setTimeout(() => resolve(timedOut), timeoutMs);
+        });
+        const result = await Promise.race([
+            this._postEncodeQueue.then(() => true),
+            timeoutPromise,
+        ]);
+        if (timeout)
+            clearTimeout(timeout);
+        const drained = result === true && this._pendingPostEncodeIds.size === 0;
+        return {
+            drained,
+            pendingIds: this.pendingConsolidationIds(),
+        };
+    }
+    async encode(params) {
+        return this._encodeInternal(params);
+    }
+    async encodeWithDiagnostics(params) {
+        const profile = new ProfileRecorder('memory_encode');
+        const id = await this._encodeInternal(params, profile);
+        return { id, diagnostics: profile.finish() };
+    }
+    async _encodeInternal(params, profile) {
+        await this._waitForEmbeddingWarmup(profile, 'encode.wait_for_warmup');
+        if (profile)
+            await profile.measure('encode.ensure_migrated', () => this._ensureMigrated());
+        else
+            await this._ensureMigrated();
+        const encodeParams = { ...params, agent: params.agent ?? this.agent, arousalWeight: this.affectConfig.arousalWeight };
+        let encodedVector;
+        let encodedBuffer;
+        const id = profile
+            ? await profile.measure('encode.episode', () => encodeEpisode(this.db, this.embeddingProvider, encodeParams, {
+                profile,
+                onVector: (vector, buffer) => {
+                    encodedVector = vector;
+                    encodedBuffer = buffer;
+                },
+            }))
+            : await encodeEpisode(this.db, this.embeddingProvider, encodeParams, {
+                onVector: (vector, buffer) => {
+                    encodedVector = vector;
+                    encodedBuffer = buffer;
+                },
+            });
+        const encodedEmbedding = { vector: encodedVector, buffer: encodedBuffer };
+        this.emit('encode', { id, ...params });
+        const postEncodeTask = profile
+            ? profile.measureSync('encode.enqueue_background', () => this._enqueuePostEncode(id, params, encodedEmbedding))
+            : this._enqueuePostEncode(id, params, encodedEmbedding);
+        if (params.waitForConsolidation) {
+            if (profile)
+                await profile.measure('encode.wait_for_consolidation', () => postEncodeTask);
+            else
+                await postEncodeTask;
         }
-        this._emitValidation(id, params);
         return id;
     }
     async reflect(turns) {
@@ -158,7 +419,15 @@ export class Audrey extends EventEmitter {
         const prompt = buildReflectionPrompt(turns);
         let raw;
         try {
-            raw = await this.llmProvider.chat(prompt);
+            if (typeof this.llmProvider.complete === 'function') {
+                raw = (await this.llmProvider.complete(prompt)).content;
+            }
+            else if (typeof this.llmProvider.chat === 'function') {
+                raw = await this.llmProvider.chat(messagesToLegacyPrompt(prompt));
+            }
+            else {
+                return { encoded: 0, memories: [], skipped: 'llm provider missing completion method' };
+            }
         }
         catch (err) {
             this.emit('error', err);
@@ -171,11 +440,11 @@ export class Audrey extends EventEmitter {
         catch {
             return { encoded: 0, memories: [], skipped: 'invalid llm response' };
         }
-        const memories = parsed.memories ?? [];
+        const memories = Array.isArray(parsed.memories)
+            ? parsed.memories.map(normalizeReflectionMemory).filter((mem) => mem !== null).slice(0, 50)
+            : [];
         let encoded = 0;
         for (const mem of memories) {
-            if (!mem.content || !mem.source)
-                continue;
             try {
                 await this.encode({
                     content: mem.content,
@@ -191,32 +460,78 @@ export class Audrey extends EventEmitter {
                 this.emit('error', err);
             }
         }
-        return { encoded, memories: memories };
+        return { encoded, memories };
     }
     async encodeBatch(paramsList) {
+        await this._waitForEmbeddingWarmup();
         await this._ensureMigrated();
-        const ids = [];
         for (const params of paramsList) {
-            const id = await encodeEpisode(this.db, this.embeddingProvider, params);
+            validateEncodeParams(params);
+        }
+        const normalized = paramsList.map(params => ({
+            ...params,
+            agent: params.agent ?? this.agent,
+            arousalWeight: this.affectConfig.arousalWeight,
+        }));
+        const vectors = await this.embeddingProvider.embedBatch(normalized.map(params => params.content));
+        if (vectors.length !== normalized.length) {
+            throw new Error(`embedBatch returned ${vectors.length} vectors for ${normalized.length} inputs`);
+        }
+        const ids = [];
+        const tasks = [];
+        for (let i = 0; i < normalized.length; i++) {
+            const encodeParams = normalized[i];
+            let encodedVector;
+            let encodedBuffer;
+            const id = await encodeEpisode(this.db, this.embeddingProvider, encodeParams, {
+                vector: vectors[i],
+                onVector: (vector, buffer) => {
+                    encodedVector = vector;
+                    encodedBuffer = buffer;
+                },
+            });
             ids.push(id);
-            this.emit('encode', { id, ...params });
+            this.emit('encode', { id, ...paramsList[i] });
+            const encodedEmbedding = { vector: encodedVector, buffer: encodedBuffer };
+            tasks.push(this._enqueuePostEncode(id, paramsList[i], encodedEmbedding));
         }
-        for (let i = 0; i < ids.length; i++) {
-            this._emitValidation(ids[i], paramsList[i]);
+        if (paramsList.some(p => p.waitForConsolidation)) {
+            await Promise.all(tasks);
         }
         return ids;
     }
     async recall(query, options = {}) {
-        await this._ensureMigrated();
-        return recallFn(this.db, this.embeddingProvider, query, {
+        return this._recallInternal(query, options);
+    }
+    async recallWithDiagnostics(query, options = {}) {
+        const profile = new ProfileRecorder('memory_recall');
+        const results = await this._recallInternal(query, options, profile);
+        return { results, diagnostics: profile.finish() };
+    }
+    async _recallInternal(query, options = {}, profile) {
+        await this._waitForEmbeddingWarmup(profile, 'recall.wait_for_warmup');
+        if (profile)
+            await profile.measure('recall.ensure_migrated', () => this._ensureMigrated());
+        else
+            await this._ensureMigrated();
+        const results = await recallFn(this.db, this.embeddingProvider, query, {
             ...options,
+            agent: options.agent ?? this.agent,
+            retrieval: options.retrieval ?? this.defaultRetrievalMode,
             confidenceConfig: this._recallConfig(options),
+            profile,
         });
+        this._lastRecallCheckAt = new Date().toISOString();
+        this._lastRecallErrors = results.errors ?? [];
+        return results;
     }
     async *recallStream(query, options = {}) {
+        await this._waitForEmbeddingWarmup();
         await this._ensureMigrated();
         yield* recallStreamFn(this.db, this.embeddingProvider, query, {
             ...options,
+            agent: options.agent ?? this.agent,
+            retrieval: options.retrieval ?? this.defaultRetrievalMode,
             confidenceConfig: this._recallConfig(options),
         });
     }
@@ -232,20 +547,22 @@ export class Audrey extends EventEmitter {
     }
     async consolidate(options = {}) {
         await this._ensureMigrated();
+        // Use ?? throughout so 0 / '' are not silently replaced with the default.
         const result = await runConsolidation(this.db, this.embeddingProvider, {
-            minClusterSize: options.minClusterSize || this.consolidationConfig.minEpisodes,
-            similarityThreshold: options.similarityThreshold || 0.80,
+            minClusterSize: options.minClusterSize ?? this.consolidationConfig.minEpisodes,
+            similarityThreshold: options.similarityThreshold ?? 0.80,
+            agent: options.agent ?? this.agent,
             extractPrinciple: options.extractPrinciple,
-            llmProvider: options.llmProvider || this.llmProvider || undefined,
+            llmProvider: options.llmProvider ?? this.llmProvider ?? undefined,
         });
         const run = db_prepare_get_status(this.db, result.runId);
-        const output = { ...result, status: run?.status || 'completed' };
+        const output = { ...result, status: run?.status ?? 'completed' };
         this.emit('consolidation', output);
         return output;
     }
     decay(options = {}) {
         const result = applyDecay(this.db, {
-            dormantThreshold: options.dormantThreshold || this.decayConfig.dormantThreshold,
+            dormantThreshold: options.dormantThreshold ?? this.decayConfig.dormantThreshold,
             halfLives: options.halfLives ?? this.confidenceConfig.halfLives,
         });
         this.emit('decay', result);
@@ -352,14 +669,23 @@ export class Audrey extends EventEmitter {
             device: device ?? null,
             healthy,
             reembed_recommended: reembedRecommended,
+            pending_consolidation_count: this._pendingPostEncodeIds.size,
+            embedding_warm: this._embeddingWarm,
+            warmup_duration_ms: this._warmupDurationMs,
+            default_retrieval_mode: this.defaultRetrievalMode,
+            recall_degraded: this._lastRecallErrors.length > 0,
+            last_recall_check_at: this._lastRecallCheckAt,
+            last_recall_errors: this._lastRecallErrors,
         };
     }
-    async greeting({ context, recentLimit = 10, principleLimit = 5, identityLimit = 5 } = {}) {
-        const recent = this.db.prepare('SELECT id, content, source, tags, salience, created_at FROM episodes WHERE "private" = 0 ORDER BY created_at DESC LIMIT ?').all(recentLimit);
-        const principles = this.db.prepare('SELECT id, content, salience, created_at FROM semantics WHERE state = ? ORDER BY salience DESC LIMIT ?').all('active', principleLimit);
-        const identity = this.db.prepare('SELECT id, content, tags, salience, created_at FROM episodes WHERE "private" = 1 ORDER BY created_at DESC LIMIT ?').all(identityLimit);
-        const unresolved = this.db.prepare("SELECT id, content, tags, salience, created_at FROM episodes WHERE tags LIKE '%unresolved%' AND salience > 0.3 ORDER BY created_at DESC LIMIT 10").all();
-        const rawAffectRows = this.db.prepare("SELECT affect FROM episodes WHERE affect IS NOT NULL AND affect != '{}' ORDER BY created_at DESC LIMIT 20").all();
+    async greeting({ context, recentLimit = 10, principleLimit = 5, identityLimit = 5, scope = 'agent' } = {}) {
+        const agentClause = scope === 'agent' ? 'AND agent = ?' : '';
+        const agentParam = scope === 'agent' ? [this.agent] : [];
+        const recent = this.db.prepare(`SELECT id, content, source, tags, salience, created_at FROM episodes WHERE "private" = 0 ${agentClause} ORDER BY created_at DESC LIMIT ?`).all(...agentParam, recentLimit);
+        const principles = this.db.prepare(`SELECT id, content, salience, created_at FROM semantics WHERE state = ? ${agentClause} ORDER BY salience DESC LIMIT ?`).all('active', ...agentParam, principleLimit);
+        const identity = this.db.prepare(`SELECT id, content, tags, salience, created_at FROM episodes WHERE "private" = 1 ${agentClause} ORDER BY created_at DESC LIMIT ?`).all(...agentParam, identityLimit);
+        const unresolved = this.db.prepare(`SELECT id, content, tags, salience, created_at FROM episodes WHERE tags LIKE '%unresolved%' AND salience > 0.3 ${agentClause} ORDER BY created_at DESC LIMIT 10`).all(...agentParam);
+        const rawAffectRows = this.db.prepare(`SELECT affect FROM episodes WHERE affect IS NOT NULL AND affect != '{}' ${agentClause} ORDER BY created_at DESC LIMIT 20`).all(...agentParam);
         const affectParsed = rawAffectRows
             .map(r => { try {
             return JSON.parse(r.affect);
@@ -383,7 +709,7 @@ export class Audrey extends EventEmitter {
         }
         const result = { recent, principles, mood, unresolved, identity };
         if (context) {
-            result.contextual = await this.recall(context, { limit: 5, includePrivate: true });
+            result.contextual = await this.recall(context, { limit: 5, includePrivate: true, scope });
         }
         return result;
     }
@@ -434,6 +760,37 @@ export class Audrey extends EventEmitter {
     suggestConsolidationParams() {
         return suggestParamsFn(this.db);
     }
+    validate(input) {
+        const result = applyFeedback(this.db, input);
+        if (result) {
+            // Audit row in memory_events so audrey impact can show
+            // helpful-vs-wrong breakdown over a window. Outcome is mapped onto the
+            // events-table enum: helpful → succeeded, wrong → failed, used → unknown.
+            // The original outcome string is preserved in metadata.
+            const eventOutcome = input.outcome === 'helpful' ? 'succeeded'
+                : input.outcome === 'wrong' ? 'failed'
+                    : 'unknown';
+            insertEvent(this.db, {
+                eventType: 'Validate',
+                source: 'memory_validate',
+                actorAgent: this.agent,
+                outcome: eventOutcome,
+                redactionState: 'clean',
+                metadata: {
+                    memory_id: result.id,
+                    memory_type: result.type,
+                    outcome: input.outcome,
+                    salience_after: result.salience,
+                    usage_count_after: result.usageCount,
+                },
+            });
+            this.emit('validate', result);
+        }
+        return result;
+    }
+    impact(options = {}) {
+        return buildImpactReport(this.db, options.windowDays ?? 7, options.limit ?? 5);
+    }
     forget(id, options = {}) {
         const result = forgetMemory(this.db, id, options);
         this.emit('forget', result);
@@ -456,10 +813,28 @@ export class Audrey extends EventEmitter {
             return;
         this._closed = true;
         this.stopAutoConsolidate();
+        if (this._pendingPostEncodeIds.size > 0) {
+            // Sync close() can't await; emit a clear signal so callers can spot data loss.
+            // Use closeAsync() (preferred) or call drainPostEncodeQueue() before close() to avoid this.
+            console.error(`[audrey] close() called with ${this._pendingPostEncodeIds.size} pending post-encode tasks ` +
+                `(use closeAsync() or await drainPostEncodeQueue() first to avoid losing consolidation work)`);
+        }
         closeDatabase(this.db);
     }
+    async closeAsync(timeoutMs = 5000) {
+        if (this._closed)
+            return undefined;
+        let result;
+        if (this._pendingPostEncodeIds.size > 0) {
+            result = await this.drainPostEncodeQueue(timeoutMs);
+        }
+        this._closed = true;
+        this.stopAutoConsolidate();
+        closeDatabase(this.db);
+        return result;
+    }
     async waitForIdle() {
-        return Promise.resolve();
+        await this._postEncodeQueue;
     }
     observeTool(input) {
         const result = observeTool(this.db, {
@@ -483,6 +858,16 @@ export class Audrey extends EventEmitter {
         this.emit('capsule', capsule);
         return capsule;
     }
+    async preflight(action, options = {}) {
+        const preflight = await buildPreflight(this, action, options);
+        this.emit('preflight', preflight);
+        return preflight;
+    }
+    async reflexes(action, options = {}) {
+        const report = await buildReflexReport(this, action, options);
+        this.emit('reflexes', report);
+        return report;
+    }
     findPromotionCandidates(options = {}) {
         return findPromotionCandidates(this.db, options);
     }
@@ -499,6 +884,28 @@ export class Audrey extends EventEmitter {
         });
         const dryRun = options.dryRun ?? !options.yes;
         const projectDir = pathResolve(options.projectDir ?? process.cwd());
+        // Guard against malicious project_dir from MCP/HTTP callers writing
+        // .claude/rules/*.md to arbitrary locations — those files are read by
+        // Claude Code on the next session, making this a persistent
+        // prompt-injection vector. By default the path must be under cwd or one
+        // of the explicit AUDREY_PROMOTE_ROOTS entries.
+        if (!dryRun) {
+            const allowedRoots = [pathResolve(process.cwd())];
+            const extra = process.env.AUDREY_PROMOTE_ROOTS;
+            if (extra) {
+                for (const root of extra.split(/[:;]/).map(s => s.trim()).filter(Boolean)) {
+                    allowedRoots.push(pathResolve(root));
+                }
+            }
+            const isUnderAllowedRoot = allowedRoots.some(root => {
+                const rel = relative(root, projectDir);
+                return rel === '' || (!rel.startsWith('..') && !pathIsAbsolute(rel));
+            });
+            if (!isUnderAllowedRoot) {
+                throw new Error(`promote: refusing to write to ${projectDir} — path is outside cwd and AUDREY_PROMOTE_ROOTS. ` +
+                    `Set AUDREY_PROMOTE_ROOTS=<path1>:<path2> to allow additional locations.`);
+            }
+        }
         const promotedAt = new Date().toISOString();
         const docs = renderAllRules(candidates, promotedAt);
         const applied = [];