audrey 1.3.0 → 2.1.0

package/dist/src/audrey.js

@@ -1,8 +1,9 @@
 import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
 import { createDatabase, closeDatabase, liveRowClause, refreshVectorRow } from './db.js';
 import { createEmbeddingProvider } from './embedding.js';
 import { createLLMProvider } from './llm.js';
-import { encodeEpisode } from './encode.js';
+import { encodeEpisode, assertEncodeInput } from './encode.js';
 import { redact } from './redact.js';
 import { recall as recallFn, recallStream as recallStreamFn } from './recall.js';
 import { validateMemory } from './validate.js';
@@ -27,15 +28,15 @@ import { buildPreflight } from './preflight.js';
 import { buildReflexReport } from './reflexes.js';
 import { beforeAction as guardBeforeAction, afterAction as guardAfterAction, } from './controller.js';
 import { findPromotionCandidates, } from './promote.js';
-import { renderAllRules } from './rules-compiler.js';
-import { insertEvent } from './events.js';
+import { renderAllRules, legacyClaudeRuleRelativePath, claudeRuleHasProvenance, } from './rules-compiler.js';
+import { insertEvent, recordPromotion } from './events.js';
 import { requireAgent, resolveMemoryScope, isContainedIn } from './utils.js';
-import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, lstatSync, openSync, closeSync, fsyncSync, linkSync, rmSync, } from 'node:fs';
 import { dirname, join, resolve as pathResolve, delimiter as pathDelimiter } from 'node:path';
 import { ProfileRecorder } from './profile.js';
 import { performance } from 'node:perf_hooks';
 import { recordAnchors, verifyAnchors, } from './grounding.js';
-import { projectRoot } from './project.js';
+import { checkoutRoot } from './project.js';
 /**
  * Thrown by `Audrey.validate()` when a structural lineage check fails. Carries a
  * stable `code` so HTTP and MCP callers can branch on the failure type without
@@ -52,16 +53,31 @@ export class ValidateLineageError extends Error {
 function roundMs(value) {
     return Math.round(value * 1000) / 1000;
 }
+/** Create and fill a file only if it does not exist; false when it already does. */
+function writeExclusively(path, body) {
+    let fd;
+    try {
+        fd = openSync(path, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    try {
+        writeFileSync(fd, body, 'utf8');
+        fsyncSync(fd);
+    }
+    catch (error) {
+        closeSync(fd);
+        rmSync(path, { force: true });
+        throw error;
+    }
+    closeSync(fd);
+    return true;
+}
 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');
-    }
+    assertEncodeInput(params);
 }
 const TRUTH_RESOLUTIONS = new Set([
     'a_wins',
@@ -188,6 +204,7 @@ export class Audrey extends EventEmitter {
     defaultRetrievalMode;
     autoReflect;
     _migrationPending;
+    _migrationPromise = null;
     _autoConsolidateTimer;
     _closed;
     _postEncodeQueue;
@@ -197,7 +214,7 @@ export class Audrey extends EventEmitter {
     _warmupDurationMs;
     _lastRecallCheckAt;
     _lastRecallErrors;
-    constructor({ dataDir = './audrey-data', agent = 'default', embedding = { provider: 'mock', dimensions: 64 }, llm, confidence = {}, consolidation = {}, decay = {}, interference = {}, context = {}, affect = {}, autoReflect = false, } = {}) {
+    constructor({ dataDir = './audrey-data', sharedStore, agent = 'default', embedding = { provider: 'mock', dimensions: 64 }, llm, confidence = {}, consolidation = {}, decay = {}, interference = {}, context = {}, affect = {}, autoReflect = false, } = {}) {
         super();
         const dormantThreshold = decay.dormantThreshold ?? 0.1;
         if (dormantThreshold < 0 || dormantThreshold > 1) {
@@ -212,6 +229,7 @@ export class Audrey extends EventEmitter {
         this.embeddingProvider = createEmbeddingProvider(embedding);
         const { db, migrated } = createDatabase(dataDir, {
             dimensions: this.embeddingProvider.dimensions,
+            sharedStore,
         });
         this.db = db;
         this._migrationPending = migrated;
@@ -276,9 +294,15 @@ export class Audrey extends EventEmitter {
     async _ensureMigrated() {
         if (!this._migrationPending)
             return;
-        const counts = await reembedAll(this.db, this.embeddingProvider);
-        this._migrationPending = false;
-        this.emit('migration', counts);
+        this._migrationPromise ??= reembedAll(this.db, this.embeddingProvider)
+            .then(counts => {
+            this._migrationPending = false;
+            this.emit('migration', counts);
+        })
+            .finally(() => {
+            this._migrationPromise = null;
+        });
+        await this._migrationPromise;
     }
     startEmbeddingWarmup(text = 'warmup') {
         if (this._embeddingWarm)
@@ -376,9 +400,9 @@ export class Audrey extends EventEmitter {
             recordAnchors(this.db, {
                 memoryId: id,
                 memoryType: 'episodic',
-                agent: this.agent,
+                agent: requireAgent(params.agent, this.agent),
                 content: params.content,
-                projectRoot: projectRoot(cwd),
+                projectRoot: checkoutRoot(cwd),
             });
         });
         await this._runPostEncodeStage('validation', async () => {
@@ -517,7 +541,7 @@ export class Audrey extends EventEmitter {
         const encodedEmbedding = { vector: encodedVector, buffer: encodedBuffer };
         if (redactionSummary?.redacted)
             this.emit('redaction', { id, ...redactionSummary });
-        this.emit('encode', { id, ...params });
+        this.emit('encode', { id, ...params, ...sanitizedFields });
         // The background pipeline (grounding, validation, the contradiction
         // prompt sent to the cloud LLM) must only ever see what the row stores.
         // Handing it the raw params would leak a secret redaction just scrubbed.
@@ -535,10 +559,14 @@ export class Audrey extends EventEmitter {
         }
         return id;
     }
-    async reflect(turns) {
+    async reflect(turns, options = {}) {
+        const agent = requireAgent(options.agent, this.agent);
         if (!this.llmProvider)
             return { encoded: 0, memories: [], skipped: 'no llm provider' };
-        const prompt = buildReflectionPrompt(turns);
+        const prompt = buildReflectionPrompt(turns.map(turn => ({
+            role: turn.role,
+            content: redact(turn.content).text,
+        })));
         let raw;
         try {
             if (typeof this.llmProvider.complete === 'function') {
@@ -573,6 +601,7 @@ export class Audrey extends EventEmitter {
             try {
                 await this.encode({
                     content: mem.content,
+                    agent,
                     source: mem.source,
                     salience: mem.salience,
                     tags: mem.tags,
@@ -629,7 +658,7 @@ export class Audrey extends EventEmitter {
             ids.push(id);
             if (redactionSummary?.redacted)
                 this.emit('redaction', { id, ...redactionSummary });
-            this.emit('encode', { id, ...paramsList[i] });
+            this.emit('encode', { id, ...paramsList[i], ...sanitizedFields });
             const encodedEmbedding = { vector: encodedVector, buffer: encodedBuffer };
             // Same boundary as _encodeInternal: background stages see stored values only.
             const postEncodeParams = sanitizedFields
@@ -774,9 +803,11 @@ export class Audrey extends EventEmitter {
                     this.db
                         .prepare("UPDATE semantics SET state = 'context_dependent', conditions = ? WHERE id = ?")
                         .run(conditions, id);
+                    refreshVectorRow(this.db, 'semantics', id);
                 }
                 else {
                     this.db.prepare('UPDATE episodes SET superseded_by = NULL WHERE id = ?').run(id);
+                    refreshVectorRow(this.db, 'episodes', id);
                 }
             };
             if (result.resolution === 'a_wins') {
@@ -897,13 +928,13 @@ export class Audrey extends EventEmitter {
         const agentClause = memoryScope === 'agent' ? 'AND agent = ?' : '';
         const agentParam = memoryScope === 'agent' ? [memoryAgent] : [];
         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 ?`)
+            .prepare(`SELECT id, content, source, tags, salience, created_at FROM episodes WHERE "private" = 0 AND superseded_by IS NULL ${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 ?`)
+            .prepare(`SELECT id, content, tags, salience, created_at FROM episodes WHERE "private" = 1 AND superseded_by IS NULL ${agentClause} ORDER BY created_at DESC LIMIT ?`)
             .all(...agentParam, identityLimit);
         const unresolved = this.db
             .prepare(`SELECT id, content, tags, salience, created_at
@@ -914,12 +945,13 @@ export class Audrey extends EventEmitter {
            WHERE json_each.type = 'text' AND json_each.value = 'unresolved'
          )
            AND salience > 0.3
+           AND superseded_by IS NULL
            ${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`)
+            .prepare(`SELECT affect FROM episodes WHERE affect IS NOT NULL AND affect != '{}' AND superseded_by IS NULL ${agentClause} ORDER BY created_at DESC LIMIT 20`)
             .all(...agentParam);
         const affectParsed = rawAffectRows
             .map(r => {
@@ -1005,7 +1037,7 @@ export class Audrey extends EventEmitter {
     suggestConsolidationParams() {
         return suggestParamsFn(this.db);
     }
-    validate(input) {
+    validate(input, deferredNotifications) {
         input = { ...input, agent: requireAgent(input.agent, this.agent) };
         let preflightMetadata = null;
         if (input.preflightEventId) {
@@ -1073,7 +1105,13 @@ export class Audrey extends EventEmitter {
                     ...(input.evidenceIds ? { preflight_evidence_ids: input.evidenceIds } : {}),
                 },
             });
-            this.emit('validate', result);
+            const notify = () => {
+                this.emit('validate', result);
+            };
+            if (deferredNotifications)
+                deferredNotifications.push(notify);
+            else
+                notify();
         }
         return result;
     }
@@ -1134,12 +1172,18 @@ export class Audrey extends EventEmitter {
     async waitForIdle() {
         await this._postEncodeQueue;
     }
-    observeTool(input) {
+    observeTool(input, deferredNotifications) {
         const result = observeTool(this.db, {
             ...input,
             actorAgent: requireAgent(input.actorAgent, this.agent),
         });
-        this.emit('tool-observed', result.event);
+        const notify = () => {
+            this.emit('tool-observed', result.event);
+        };
+        if (deferredNotifications)
+            deferredNotifications.push(notify);
+        else
+            notify();
         return result;
     }
     listEvents(query = {}) {
@@ -1228,45 +1272,154 @@ export class Audrey extends EventEmitter {
         }
         const promotedAt = new Date().toISOString();
         const docs = renderAllRules(candidates, promotedAt);
+        const resolvedPaths = docs.map(doc => doc.relativePath);
         const applied = [];
         if (!dryRun) {
             for (let i = 0; i < candidates.length; i++) {
                 const candidate = candidates[i];
                 const doc = docs[i];
                 const absolutePath = join(projectDir, doc.relativePath);
+                if (!isContainedIn(projectDir, absolutePath)) {
+                    throw new Error('promote: refusing to write a rule outside the project through a symlink');
+                }
                 mkdirSync(dirname(absolutePath), { recursive: true });
-                const overwritten = existsSync(absolutePath);
-                writeFileSync(absolutePath, doc.body, 'utf-8');
-                insertEvent(this.db, {
-                    eventType: 'Promotion',
-                    source: 'promote-command',
+                if (!isContainedIn(projectDir, absolutePath)) {
+                    throw new Error('promote: rule destination changed outside the project');
+                }
+                const promotion = {
+                    target,
                     actorAgent: this.agent,
-                    toolName: target,
-                    outcome: 'succeeded',
-                    cwd: projectDir,
-                    fileFingerprints: [doc.relativePath],
-                    redactionState: 'clean',
-                    metadata: {
-                        memory_ids: [candidate.memory_id],
-                        memory_type: candidate.memory_type,
-                        candidate_id: candidate.candidate_id,
-                        confidence: Number(candidate.confidence.toFixed(3)),
-                        evidence_count: candidate.evidence_count,
-                        failure_prevented: candidate.failure_prevented,
-                        score: Number(candidate.score.toFixed(2)),
-                        target,
-                        absolute_path: absolutePath,
-                        relative_path: doc.relativePath,
-                        overwritten,
-                    },
-                });
+                    memoryIds: [candidate.memory_id],
+                    promotedAt,
+                };
+                const preserveExistingRule = (relativePath, mustMatch) => {
+                    const existingPath = join(projectDir, relativePath);
+                    if (!isContainedIn(projectDir, existingPath)) {
+                        throw new Error('promote: refusing to inspect a rule outside the project');
+                    }
+                    try {
+                        const existing = lstatSync(existingPath);
+                        if (existing.isSymbolicLink() || !existing.isFile()) {
+                            throw new Error('promote: refusing to replace a non-file rule destination');
+                        }
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT')
+                            return false;
+                        throw error;
+                    }
+                    if (!claudeRuleHasProvenance(readFileSync(existingPath, 'utf8'), candidate)) {
+                        if (mustMatch) {
+                            throw new Error('promote: refusing to overwrite an existing rule with different provenance');
+                        }
+                        return false;
+                    }
+                    recordPromotion(this.db, {
+                        ...promotion,
+                        relativePath,
+                        absolutePath: existingPath,
+                    });
+                    resolvedPaths[i] = relativePath;
+                    return true;
+                };
+                if (preserveExistingRule(doc.relativePath, true))
+                    continue;
+                const legacyPath = legacyClaudeRuleRelativePath(candidate);
+                const legacyDirectory = legacyPath.slice(0, legacyPath.lastIndexOf('/') + 1);
+                const legacyName = legacyPath.slice(legacyDirectory.length);
+                const legacyStem = legacyName.slice(0, -3);
+                // Older renderAllRules disambiguated colliding truncated IDs with
+                // numbered suffixes. Inspect actual files, rather than guessing how
+                // many suffixes were once written, and require the complete provenance.
+                const legacyNames = readdirSync(dirname(absolutePath), { withFileTypes: true })
+                    .filter(entry => entry.isFile())
+                    .map(entry => entry.name)
+                    .filter(name => name === legacyName ||
+                    (name.startsWith(`${legacyStem}-`) &&
+                        /^[1-9][0-9]*\.md$/.test(name.slice(legacyStem.length + 1))));
+                if (legacyNames.some(name => preserveExistingRule(legacyDirectory + name, false)))
+                    continue;
+                // Publish a complete file only if its destination is still absent.
+                // A racing promotion must never overwrite an existing, edited rule.
+                const temporary = `${absolutePath}.${randomUUID()}.tmp`;
+                try {
+                    const fd = openSync(temporary, 'wx', 0o600);
+                    try {
+                        writeFileSync(fd, doc.body, 'utf8');
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                    if (!isContainedIn(projectDir, dirname(absolutePath))) {
+                        throw new Error('promote: rule directory changed outside the project');
+                    }
+                    try {
+                        linkSync(temporary, absolutePath);
+                    }
+                    catch (error) {
+                        const code = error.code;
+                        if (code === 'EEXIST') {
+                            if (preserveExistingRule(doc.relativePath, true))
+                                continue;
+                            throw error;
+                        }
+                        // Filesystems without hard links (exFAT, some network and container
+                        // mounts) keep the no-overwrite guarantee through an exclusive create.
+                        if (code !== 'EPERM' && code !== 'ENOTSUP' && code !== 'EXDEV' && code !== 'ENOSYS') {
+                            throw error;
+                        }
+                        if (!writeExclusively(absolutePath, doc.body)) {
+                            if (preserveExistingRule(doc.relativePath, true))
+                                continue;
+                            throw new Error(`promote: rule destination already exists: ${doc.relativePath}`, {
+                                cause: error,
+                            });
+                        }
+                    }
+                }
+                finally {
+                    rmSync(temporary, { force: true });
+                }
+                this.db
+                    .transaction(() => {
+                    recordPromotion(this.db, {
+                        ...promotion,
+                        relativePath: doc.relativePath,
+                        absolutePath,
+                    });
+                    insertEvent(this.db, {
+                        eventType: 'Promotion',
+                        source: 'promote-command',
+                        actorAgent: this.agent,
+                        toolName: target,
+                        outcome: 'succeeded',
+                        cwd: projectDir,
+                        fileFingerprints: [doc.relativePath],
+                        redactionState: 'clean',
+                        metadata: {
+                            memory_ids: [candidate.memory_id],
+                            memory_type: candidate.memory_type,
+                            candidate_id: candidate.candidate_id,
+                            confidence: Number(candidate.confidence.toFixed(3)),
+                            evidence_count: candidate.evidence_count,
+                            failure_prevented: candidate.failure_prevented,
+                            score: Number(candidate.score.toFixed(2)),
+                            target,
+                            absolute_path: absolutePath,
+                            relative_path: doc.relativePath,
+                            overwritten: false,
+                        },
+                    });
+                })
+                    .immediate();
                 applied.push({
                     candidate_id: candidate.candidate_id,
                     memory_id: candidate.memory_id,
                     target,
                     relative_path: doc.relativePath,
                     absolute_path: absolutePath,
-                    overwritten,
+                    overwritten: false,
                 });
             }
         }
@@ -1277,7 +1430,7 @@ export class Audrey extends EventEmitter {
             promoted_at: promotedAt,
             candidates: candidates.map((c, i) => ({
                 ...c,
-                rendered_path: docs[i].relativePath,
+                rendered_path: resolvedPaths[i],
             })),
             applied,
         };