@devflow-tools/memory-engine 0.16.10 → 0.16.12

package/dist/memory-store.js

@@ -2,11 +2,13 @@ import Database from 'better-sqlite3';
 import * as sqliteVec from 'sqlite-vec';
 import { dirname, join } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { applyV2ToV3Migration } from './migrations/v2-to-v3.js';
 import { applyV3ToV4Migration } from './migrations/v3-to-v4.js';
 import { applyV4ToV5Migration } from './migrations/v4-to-v5.js';
+import { applyV6ToV7Migration } from './migrations/v6-to-v7.js';
 import { observationDedupKey, } from './observation-types.js';
+import { analysesConflict, analyzePreference, analyzePreferenceObservation, } from './preference-conflicts.js';
 // ── Schema ─────────────────────────────────────────────
 const SCHEMA_V2 = `
 -- ============================================================
@@ -169,7 +171,8 @@ CREATE TABLE IF NOT EXISTS observations (
   source_event_ids TEXT NOT NULL DEFAULT '[]',
   memory_id        TEXT,
   embedding        BLOB,
-  timestamp        INTEGER NOT NULL
+  timestamp        INTEGER NOT NULL,
+  explicit_accepted_at INTEGER
 );
 CREATE INDEX IF NOT EXISTS idx_observations_session ON observations(session_id);
 CREATE INDEX IF NOT EXISTS idx_observations_project ON observations(project);
@@ -256,6 +259,126 @@ CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
   VALUES (new.rowid, new.id, new.content, new.scope);
 END;
 `;
+const OBSERVATION_FTS_SCHEMA = `
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+  id UNINDEXED,
+  title,
+  narrative,
+  facts,
+  concepts,
+  tokenize='trigram'
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_terms_fts USING fts5(
+  id UNINDEXED,
+  title,
+  narrative,
+  facts,
+  concepts,
+  tokenize = "unicode61 tokenchars '#+'"
+);
+
+CREATE TRIGGER IF NOT EXISTS observations_fts_ai
+AFTER INSERT ON observations
+WHEN new.quality_status = 'accepted' AND new.resolution_state = 'current'
+BEGIN
+  INSERT INTO observations_fts(rowid, id, title, narrative, facts, concepts)
+  VALUES (new.rowid, new.id, new.title, new.narrative, new.facts, new.concepts);
+  INSERT INTO observations_terms_fts(rowid, id, title, narrative, facts, concepts)
+  VALUES (new.rowid, new.id, new.title, new.narrative, new.facts, new.concepts);
+END;
+
+CREATE TRIGGER IF NOT EXISTS observations_fts_ad
+AFTER DELETE ON observations
+WHEN old.quality_status = 'accepted' AND old.resolution_state = 'current'
+BEGIN
+  DELETE FROM observations_fts WHERE rowid = old.rowid;
+  DELETE FROM observations_terms_fts WHERE rowid = old.rowid;
+END;
+
+CREATE TRIGGER IF NOT EXISTS observations_fts_au
+AFTER UPDATE OF title, narrative, facts, concepts, quality_status, resolution_state ON observations
+BEGIN
+  DELETE FROM observations_fts WHERE rowid = old.rowid;
+  DELETE FROM observations_terms_fts WHERE rowid = old.rowid;
+  INSERT INTO observations_fts(rowid, id, title, narrative, facts, concepts)
+  SELECT new.rowid, new.id, new.title, new.narrative, new.facts, new.concepts
+  WHERE new.quality_status = 'accepted' AND new.resolution_state = 'current';
+  INSERT INTO observations_terms_fts(rowid, id, title, narrative, facts, concepts)
+  SELECT new.rowid, new.id, new.title, new.narrative, new.facts, new.concepts
+  WHERE new.quality_status = 'accepted' AND new.resolution_state = 'current';
+END;
+`;
+const MAX_OBSERVATION_FTS_QUERY_LENGTH = 512;
+const MAX_OBSERVATION_FTS_TERMS = 16;
+const MAX_OBSERVATION_FTS_TERM_LENGTH = 64;
+const OBSERVATION_FTS_SCHEMA_VERSION = 6;
+const OBSERVATION_EXCLUSION_CTE = `
+  WITH excluded_observation_ids(id) AS (
+    SELECT CAST(value AS TEXT) FROM json_each(?)
+  )
+`;
+function serializeObservationSearchExcludedIds(excludedIds) {
+    return JSON.stringify(excludedIds ? [...excludedIds] : []);
+}
+function normalizeObservationLexicalQuery(query) {
+    const phrase = query
+        .slice(0, MAX_OBSERVATION_FTS_QUERY_LENGTH)
+        .normalize('NFKC')
+        .slice(0, MAX_OBSERVATION_FTS_QUERY_LENGTH)
+        .replace(/\s+/gu, ' ')
+        .trim();
+    if (!phrase)
+        return { trigramQuery: null, termQuery: null };
+    const lexicalTerms = phrase.match(/[\p{L}\p{N}]+/gu) ?? [];
+    const compact = lexicalTerms.join('');
+    const candidates = [compact, phrase, ...lexicalTerms];
+    const trigramTerms = [];
+    const termTerms = [];
+    const seenTrigrams = new Set();
+    const seenTerms = new Set();
+    for (const candidate of candidates) {
+        const term = [...candidate].slice(0, MAX_OBSERVATION_FTS_TERM_LENGTH).join('');
+        const searchableCharacters = term.match(/[\p{L}\p{N}]/gu) ?? [];
+        const normalized = term.toLocaleLowerCase('en-US');
+        const quoted = `"${term.replaceAll('"', '""')}"`;
+        if (searchableCharacters.length >= 3 && !seenTrigrams.has(normalized)) {
+            seenTrigrams.add(normalized);
+            trigramTerms.push(quoted);
+        }
+        if (searchableCharacters.length >= 1 && !seenTerms.has(normalized)) {
+            seenTerms.add(normalized);
+            termTerms.push(quoted);
+        }
+        if (trigramTerms.length >= MAX_OBSERVATION_FTS_TERMS
+            && termTerms.length >= MAX_OBSERVATION_FTS_TERMS)
+            break;
+    }
+    return {
+        trigramQuery: trigramTerms.length > 0
+            ? trigramTerms.slice(0, MAX_OBSERVATION_FTS_TERMS).join(' OR ')
+            : null,
+        termQuery: termTerms.length > 0
+            ? termTerms.slice(0, MAX_OBSERVATION_FTS_TERMS).join(' OR ')
+            : null,
+    };
+}
+export function isRecoverableObservationFtsError(error) {
+    const candidate = error;
+    const code = typeof candidate?.code === 'string' ? candidate.code.toUpperCase() : '';
+    const message = typeof candidate?.message === 'string' ? candidate.message : '';
+    if (/^SQLITE_(?:BUSY|LOCKED|READONLY|IOERR|FULL|CANTOPEN|PERM)/.test(code))
+        return false;
+    if (code === 'SQLITE_CORRUPT_VTAB')
+        return true;
+    const referencesObservationFts = /observations_(?:terms_)?fts(?:_(?:data|idx|content|docsize|config))?/i
+        .test(message);
+    if (!referencesObservationFts)
+        return false;
+    if (/^SQLITE_CORRUPT(?:_|$)/.test(code))
+        return true;
+    return code === 'SQLITE_ERROR' && /no such table|malformed schema|vtable constructor failed/i.test(message);
+}
 // ── MemoryStore ─────────────────────────────────────────
 export class MemoryStore {
     db;
@@ -275,10 +398,13 @@ export class MemoryStore {
         sqliteVec.load(this.db);
         this.db.exec(SCHEMA_V2);
         this.db.exec(FTS_TRIGGERS);
+        this.dropOrphanedObservationFtsTriggers();
         this.migrateV1ToV2();
         applyV2ToV3Migration(this.db);
         applyV3ToV4Migration(this.db);
         applyV4ToV5Migration(this.db);
+        this.ensureObservationFts();
+        applyV6ToV7Migration(this.db);
         this.repairOrphanSessions(rootPath);
         console.log('[MemoryStore] Schema initialized', {
             dbPath: this.dbPath,
@@ -292,6 +418,66 @@ export class MemoryStore {
         const row = this.db.prepare("SELECT COUNT(*) as c FROM sqlite_master WHERE type='table'").get();
         return row.c;
     }
+    dropOrphanedObservationFtsTriggers() {
+        const ftsTables = this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('observations_fts', 'observations_terms_fts')").all();
+        if (ftsTables.length === 2)
+            return;
+        this.db.exec(`
+      DROP TRIGGER IF EXISTS observations_fts_ai;
+      DROP TRIGGER IF EXISTS observations_fts_ad;
+      DROP TRIGGER IF EXISTS observations_fts_au;
+    `);
+    }
+    ensureObservationFts(forceRebuild = false) {
+        this.db.transaction(() => {
+            const ftsTableCount = this.db.prepare("SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name IN ('observations_fts', 'observations_terms_fts')").get().count;
+            const migrationApplied = this.db.prepare('SELECT 1 FROM schema_versions WHERE version = ?').get(OBSERVATION_FTS_SCHEMA_VERSION) !== undefined;
+            const triggersCurrent = this.db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM sqlite_master
+        WHERE type = 'trigger'
+          AND name IN ('observations_fts_ai', 'observations_fts_ad', 'observations_fts_au')
+          AND sql LIKE '%observations_terms_fts%'
+      `).get().count === 3;
+            const needsRebuild = forceRebuild
+                || ftsTableCount !== 2
+                || !migrationApplied
+                || !triggersCurrent;
+            if (needsRebuild) {
+                this.db.exec(`
+          DROP TRIGGER IF EXISTS observations_fts_ai;
+          DROP TRIGGER IF EXISTS observations_fts_ad;
+          DROP TRIGGER IF EXISTS observations_fts_au;
+        `);
+            }
+            if (forceRebuild) {
+                this.db.exec(`
+          DROP TABLE IF EXISTS observations_fts;
+          DROP TABLE IF EXISTS observations_terms_fts;
+        `);
+            }
+            this.db.exec(OBSERVATION_FTS_SCHEMA);
+            if (!needsRebuild)
+                return;
+            this.db.exec(`
+        DELETE FROM observations_fts;
+        DELETE FROM observations_terms_fts;
+
+        INSERT INTO observations_fts(rowid, id, title, narrative, facts, concepts)
+        SELECT o.rowid, o.id, o.title, o.narrative, o.facts, o.concepts
+        FROM observations o
+        WHERE o.quality_status = 'accepted'
+          AND o.resolution_state = 'current';
+
+        INSERT INTO observations_terms_fts(rowid, id, title, narrative, facts, concepts)
+        SELECT o.rowid, o.id, o.title, o.narrative, o.facts, o.concepts
+        FROM observations o
+        WHERE o.quality_status = 'accepted'
+          AND o.resolution_state = 'current';
+      `);
+            this.db.prepare('INSERT OR REPLACE INTO schema_versions(version, applied_at) VALUES (?, ?)').run(OBSERVATION_FTS_SCHEMA_VERSION, Date.now());
+        })();
+    }
     // ── V1 → V2 Migration ────────────────────────────
     migrateV1ToV2() {
         const tables = this.db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(r => r.name);
@@ -503,16 +689,18 @@ export class MemoryStore {
         const row = this.db.prepare('SELECT vector FROM embeddings WHERE source_type = ? AND source_id = ?').get(sourceType, sourceId);
         return row?.vector ?? null;
     }
-    searchObservationVector(embedding, limit = 20) {
+    searchObservationVector(embedding, limit = 20, excludedIds) {
         const buffer = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
-        const rows = this.db.prepare(`
+        const excludedJson = serializeObservationSearchExcludedIds(excludedIds);
+        const rows = this.db.prepare(`${OBSERVATION_EXCLUSION_CTE}
       SELECT o.*, vec_distance_cosine(o.embedding, ?) AS distance
       FROM observations o
       WHERE o.embedding IS NOT NULL
         AND o.quality_status = 'accepted'
         AND o.resolution_state <> 'superseded'
+        AND o.id NOT IN (SELECT id FROM excluded_observation_ids)
       ORDER BY distance LIMIT ?
-    `).all(buffer, limit);
+    `).all(excludedJson, buffer, limit);
         return rows.map(row => ({ observation: row, distance: row.distance }));
     }
     // ── Search ───────────────────────────────────────
@@ -525,6 +713,66 @@ export class MemoryStore {
       ORDER BY rank LIMIT ?
     `).all(query, limit);
     }
+    searchObservationBM25(query, limit = 20, excludedIds) {
+        const normalizedQuery = normalizeObservationLexicalQuery(query);
+        if ((!normalizedQuery.trigramQuery && !normalizedQuery.termQuery) || limit <= 0)
+            return [];
+        const boundedLimit = Number.isFinite(limit)
+            ? Math.min(Math.max(Math.floor(limit), 1), 100)
+            : 20;
+        const excludedJson = serializeObservationSearchExcludedIds(excludedIds);
+        const scores = new Map();
+        const addRanked = (rows) => {
+            for (let index = 0; index < rows.length; index++) {
+                const id = rows[index].id;
+                scores.set(id, (scores.get(id) ?? 0) + 1 / (60 + index + 1));
+            }
+        };
+        if (normalizedQuery.trigramQuery) {
+            addRanked(this.searchObservationFtsWithRecovery('observations_fts', normalizedQuery.trigramQuery, boundedLimit, excludedJson));
+        }
+        if (normalizedQuery.termQuery) {
+            addRanked(this.searchObservationFtsWithRecovery('observations_terms_fts', normalizedQuery.termQuery, boundedLimit, excludedJson));
+        }
+        return [...scores]
+            .map(([id, score]) => ({ id, rank: -score }))
+            .sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id))
+            .slice(0, boundedLimit);
+    }
+    searchObservationFtsWithRecovery(table, query, limit, excludedJson) {
+        try {
+            return this.searchObservationFts(table, query, limit, excludedJson);
+        }
+        catch (error) {
+            if (!isRecoverableObservationFtsError(error))
+                throw error;
+            this.ensureObservationFts(true);
+            return this.searchObservationFts(table, query, limit, excludedJson);
+        }
+    }
+    searchObservationFts(table, query, limit, excludedJson) {
+        const sql = table === 'observations_fts' ? `${OBSERVATION_EXCLUSION_CTE}
+      SELECT o.id, bm25(observations_fts) AS rank
+      FROM observations_fts f
+      JOIN observations o ON o.rowid = f.rowid
+      WHERE observations_fts MATCH ?
+        AND o.quality_status = 'accepted'
+        AND o.resolution_state = 'current'
+        AND o.id NOT IN (SELECT id FROM excluded_observation_ids)
+      ORDER BY rank LIMIT ?
+    ` : `${OBSERVATION_EXCLUSION_CTE}
+      SELECT o.id, bm25(observations_terms_fts) AS rank
+      FROM observations_terms_fts f
+      JOIN observations o ON o.rowid = f.rowid
+      WHERE observations_terms_fts MATCH ?
+        AND o.quality_status = 'accepted'
+        AND o.resolution_state = 'current'
+        AND o.id NOT IN (SELECT id FROM excluded_observation_ids)
+      ORDER BY rank, updated_at DESC
+      LIMIT ?
+    `;
+        return this.db.prepare(sql).all(excludedJson, query, limit);
+    }
     searchVector(embedding, limit = 20) {
         const buffer = Buffer.from(embedding.buffer);
         return this.db.prepare(`
@@ -569,6 +817,123 @@ export class MemoryStore {
     getSessionEvents(sessionId) {
         return this.db.prepare('SELECT * FROM session_events WHERE session_id = ? ORDER BY created_at ASC').all(sessionId);
     }
+    reconcileDecidedTurnEventWindows(sessionId, turns, sessionEndAt = Number.MAX_SAFE_INTEGER) {
+        const normalizedSessionId = sessionId.trim();
+        if (!normalizedSessionId)
+            throw new Error('Session event reconciliation requires a session ID');
+        if (!Number.isSafeInteger(sessionEndAt) || sessionEndAt < 0) {
+            throw new Error('Session event reconciliation requires a safe session end timestamp');
+        }
+        const orderedTurns = turns.filter(turn => turn.sessionId === normalizedSessionId);
+        if (orderedTurns.length !== turns.length) {
+            throw new Error('Memory turn session does not match event reconciliation session');
+        }
+        for (let index = 1; index < orderedTurns.length; index += 1) {
+            if (orderedTurns[index].createdAt < orderedTurns[index - 1].createdAt) {
+                throw new Error('Memory turns must be ordered by createdAt for event reconciliation');
+            }
+        }
+        const selectSessionEvents = this.db.prepare(`
+      SELECT id, created_at FROM session_events
+      WHERE session_id = ? AND processed = 0 AND maintenance_status = 'active'
+      ORDER BY created_at ASC, id ASC
+    `);
+        const markCommitted = this.db.prepare(`
+      UPDATE session_events SET processed = 1
+      WHERE id = ? AND session_id = ? AND processed = 0 AND maintenance_status = 'active'
+    `);
+        const markSkipped = this.db.prepare(`
+      UPDATE session_events
+      SET processed = 1, maintenance_status = 'discarded', quarantine_reason = ?
+      WHERE id = ? AND session_id = ? AND processed = 0 AND maintenance_status = 'active'
+    `);
+        const insertAudit = this.db.prepare(`
+      INSERT INTO event_processing_audit
+        (id, event_id, disposition, reason, run_id, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+        const countAuditsForRuns = this.db.prepare(`
+      WITH requested_runs(run_id) AS (
+        SELECT DISTINCT value FROM json_each(?)
+      )
+      SELECT audit.disposition, COUNT(*) AS count
+      FROM event_processing_audit audit
+      INNER JOIN requested_runs requested ON requested.run_id = audit.run_id
+      GROUP BY audit.disposition
+    `);
+        return this.db.transaction(() => {
+            const reconciledAt = Date.now();
+            const groups = [];
+            for (const turn of orderedTurns) {
+                const current = groups.at(-1);
+                if (current?.[0]?.createdAt === turn.createdAt)
+                    current.push(turn);
+                else
+                    groups.push([turn]);
+            }
+            let processedThisRun = 0;
+            let discardedThisRun = 0;
+            let decidedTurnCount = 0;
+            let eventIndex = 0;
+            const canonicalRunIds = [];
+            const events = selectSessionEvents.all(normalizedSessionId);
+            for (let groupIndex = 0; groupIndex < groups.length; groupIndex += 1) {
+                const group = groups[groupIndex];
+                const windowStart = group[0].createdAt;
+                const windowEnd = Math.min(groups[groupIndex + 1]?.[0]?.createdAt ?? sessionEndAt, sessionEndAt);
+                while (eventIndex < events.length && events[eventIndex].created_at < windowStart)
+                    eventIndex += 1;
+                if (windowStart >= windowEnd)
+                    continue;
+                const allCanonical = group.every(turn => turn.status !== 'pending' && turn.receiptId?.startsWith('memory-receipt:'));
+                const allCommitted = allCanonical && group.every(turn => turn.status === 'committed');
+                const allSkipped = allCanonical && group.every(turn => turn.status === 'skipped');
+                const disposition = allCommitted ? 'processed' : allSkipped ? 'discarded' : null;
+                const canonicalGroup = disposition
+                    ? group.map(turn => `${turn.turnId}=${turn.receiptId}`).join(',')
+                    : '';
+                const reason = disposition
+                    ? `canonical_turn_group_${allCommitted ? 'committed' : 'skipped'}:${windowStart}:${canonicalGroup}`
+                    : '';
+                const runId = disposition
+                    ? `turn-reconcile:${createHash('sha256')
+                        .update(`${normalizedSessionId}\0${windowStart}\0${allCommitted ? 'committed' : 'skipped'}\0${canonicalGroup}`)
+                        .digest('hex').slice(0, 32)}`
+                    : '';
+                if (disposition) {
+                    decidedTurnCount += group.length;
+                    canonicalRunIds.push(runId);
+                }
+                while (eventIndex < events.length && events[eventIndex].created_at < windowEnd) {
+                    const event = events[eventIndex++];
+                    if (!disposition)
+                        continue;
+                    const changed = disposition === 'processed'
+                        ? markCommitted.run(event.id, normalizedSessionId).changes
+                        : markSkipped.run(reason, event.id, normalizedSessionId).changes;
+                    if (changed === 0)
+                        continue;
+                    if (disposition === 'processed')
+                        processedThisRun += changed;
+                    else
+                        discardedThisRun += changed;
+                    insertAudit.run(`epa:${reconciledAt}:${randomUUID().slice(0, 8)}`, event.id, disposition, reason, runId, reconciledAt);
+                }
+            }
+            const historicalCounts = canonicalRunIds.length > 0
+                ? countAuditsForRuns.all(JSON.stringify(canonicalRunIds))
+                : [];
+            const countByDisposition = new Map(historicalCounts.map(row => [row.disposition, Number(row.count)]));
+            return {
+                sessionId: normalizedSessionId,
+                turnCount: orderedTurns.length,
+                decidedTurnCount,
+                committedProcessed: countByDisposition.get('processed') ?? 0,
+                skippedDiscarded: countByDisposition.get('discarded') ?? 0,
+                remainingUndecided: events.length - processedThisRun - discardedThisRun,
+            };
+        })();
+    }
     getUnprocessedEvents() {
         const events = this.db.prepare(`SELECT * FROM session_events
        WHERE processed = 0 AND maintenance_status = 'active'
@@ -895,6 +1260,124 @@ export class MemoryStore {
             return this.getObservation(row.id);
         })();
     }
+    acceptExplicitPreference(input) {
+        return this.db.transaction(() => {
+            this.ensureSession(input.sessionId, input.project);
+            const latest = this.db.prepare(`
+        SELECT MAX(COALESCE(explicit_accepted_at, timestamp)) AS latest
+        FROM observations
+        WHERE project = ? AND type = 'user_preference' AND source = 'explicit_intent'
+      `).get(input.project);
+            const acceptedAt = Math.max(Date.now(), (latest.latest ?? 0) + 1);
+            const dedupKey = observationDedupKey('user_preference', input.title);
+            const exact = this.db.prepare('SELECT * FROM observations WHERE dedup_key = ? AND project = ?').get(dedupKey, input.project) ?? null;
+            let row;
+            if (exact) {
+                const contentChanged = exact.title !== input.title || exact.narrative !== input.content;
+                const sourceEventIds = new Set(parseStringArray(exact.source_event_ids));
+                if (input.sourceEventId)
+                    sourceEventIds.add(input.sourceEventId);
+                this.db.prepare(`
+          UPDATE observations
+          SET title = ?, narrative = ?, source = 'explicit_intent',
+            confidence = MAX(confidence, 0.95),
+            importance = MAX(importance, 10), quality_status = 'accepted',
+            quarantine_reason = NULL, quality_details = NULL, quarantined_at = NULL,
+            resolution_state = 'current', superseded_by_observation = NULL,
+            source_event_ids = ?, updated_at = ?, explicit_accepted_at = ?,
+            embedding = CASE WHEN ? = 1 THEN NULL ELSE embedding END
+          WHERE id = ?
+        `).run(input.title, input.content, JSON.stringify([...sourceEventIds]), acceptedAt, acceptedAt, contentChanged ? 1 : 0, exact.id);
+                if (contentChanged) {
+                    this.db.prepare("DELETE FROM embeddings WHERE source_type = 'observation' AND source_id = ?").run(exact.id);
+                }
+                this.incrementObservationAccess(exact.id, acceptedAt);
+                row = this.getObservation(exact.id);
+            }
+            else {
+                row = this.addObservation({
+                    sessionId: input.sessionId,
+                    project: input.project,
+                    type: 'user_preference',
+                    title: input.title,
+                    narrative: input.content,
+                    importance: 10,
+                    confidence: 0.95,
+                    source: 'explicit_intent',
+                    sourceEventIds: input.sourceEventId ? [input.sourceEventId] : [],
+                    timestamp: acceptedAt,
+                    qualityStatus: 'accepted',
+                });
+                this.db.prepare('UPDATE observations SET explicit_accepted_at = ? WHERE id = ?').run(acceptedAt, row.id);
+                row = this.getObservation(row.id);
+            }
+            this.supersedeConflictingExplicitPreferences(row, analyzePreference(input.content));
+            if (input.sourceEventId)
+                this.markEventsProcessed([input.sourceEventId]);
+            return this.getObservation(row.id);
+        })();
+    }
+    reconcileExplicitPreferenceConflicts(project = this.defaultProjectRoot) {
+        return this.db.transaction(() => {
+            const rows = this.listCurrentExplicitPreferences(project).sort((left, right) => this.explicitPreferenceAcceptanceTime(left)
+                - this.explicitPreferenceAcceptanceTime(right)
+                || left.timestamp - right.timestamp
+                || left.id.localeCompare(right.id));
+            let superseded = 0;
+            const active = [];
+            for (const row of rows) {
+                const analysis = analyzePreferenceObservation(row);
+                if (analysis.status !== 'high_confidence') {
+                    active.push({ row, analysis });
+                    continue;
+                }
+                for (let index = active.length - 1; index >= 0; index--) {
+                    const previous = active[index];
+                    if (!analysesConflict(previous.analysis, analysis))
+                        continue;
+                    this.db.prepare(`
+            UPDATE observations
+            SET resolution_state = 'superseded', superseded_by_observation = ?
+            WHERE id = ? AND resolution_state = 'current'
+          `).run(row.id, previous.row.id);
+                    active.splice(index, 1);
+                    superseded += 1;
+                }
+                active.push({ row, analysis });
+            }
+            return superseded;
+        })();
+    }
+    listCurrentExplicitPreferences(project = this.defaultProjectRoot) {
+        return this.db.prepare(`
+      SELECT * FROM observations
+      WHERE project = ? AND type = 'user_preference' AND source = 'explicit_intent'
+        AND quality_status = 'accepted' AND resolution_state = 'current'
+      ORDER BY COALESCE(explicit_accepted_at, timestamp) DESC, timestamp DESC, id DESC
+    `).all(project);
+    }
+    explicitPreferenceAcceptanceTime(row) {
+        return row.explicit_accepted_at ?? row.timestamp;
+    }
+    supersedeConflictingExplicitPreferences(winner, winnerAnalysis) {
+        if (winnerAnalysis.status !== 'high_confidence')
+            return 0;
+        const update = this.db.prepare(`
+      UPDATE observations
+      SET resolution_state = 'superseded', superseded_by_observation = ?
+      WHERE id = ? AND resolution_state = 'current'
+    `);
+        let superseded = 0;
+        for (const candidate of this.listCurrentExplicitPreferences(winner.project)) {
+            if (candidate.id === winner.id)
+                continue;
+            const analysis = analyzePreferenceObservation(candidate);
+            if (!analysesConflict(analysis, winnerAnalysis))
+                continue;
+            superseded += update.run(winner.id, candidate.id).changes;
+        }
+        return superseded;
+    }
     getObservation(id) {
         return this.db.prepare('SELECT * FROM observations WHERE id = ?').get(id) ?? null;
     }