@jmtrin/opencode-kevin 0.3.0 → 0.5.0

package/dist/plugin/MemoryService.js

@@ -1,15 +1,28 @@
+import { deterministicFixLine } from "./LessonFixer.js";
+import { computeConfidence } from "./confidence.js";
 import { fingerprint as computeFingerprint } from "./fingerprint.js";
+import { toMatchClause, tokenizeQuery } from "./query-tokenizer.js";
 import { uuidv7 } from "./uuid.js";
 const MAX_SNIPPET_CHARS = 200;
-function toSlim(mem) {
-    const rawScore = mem.metadata?.score;
-    return {
+function toSlim(mem, evidence = false) {
+    const base = {
         id: mem.id,
         type: mem.type,
         scope: mem.scope,
-        score: typeof rawScore === "number" ? rawScore : mem.relevanceScore,
+        score: typeof mem.metadata?.score ===
+            "number"
+            ? mem.metadata.score
+            : mem.relevanceScore,
         snippet: mem.content.slice(0, MAX_SNIPPET_CHARS),
     };
+    if (!evidence)
+        return base;
+    return {
+        ...base,
+        confidence: mem.confidence ?? null,
+        evidence_count: mem.evidenceCount ?? null,
+        last_verified_at: mem.lastVerifiedAt ?? null,
+    };
 }
 const TYPE_PRIORITY = {
     error: 0,
@@ -31,6 +44,10 @@ const ORIGIN_BOOST_PATTERN = 1.5;
 const ORIGIN_BOOST_CASUAL = 2;
 const ORIGIN_BOOST_AGENT = 1;
 const RECENCY_DECAY_PER_DAY = 0.95; // newer = closer to 1 (less penalty)
+// v0.5.0 (K5-008 / plan §5.6, D5-10) — DATE_NOW sentinel: deterministic
+// retrieval reads this fixed future instant instead of the wall clock,
+// making ordering a pure function of database content. Export for tests.
+export const DATE_NOW = "2099-01-01T00:00:00.000Z";
 function sqliteUtcToMs(createdAt) {
     // SQLite `datetime('now')` returns 'YYYY-MM-DD HH:MM:SS' in UTC.
     // JS Date can parse ISO 8601 with 'T' and 'Z'.
@@ -48,6 +65,41 @@ function sqliteUtcNowPlusHours(hours) {
     const pad = (n) => String(n).padStart(2, "0");
     return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
 }
+/** Shared column list for row reads (must stay in sync with MemoryRow). */
+const MEMORY_ROW_SELECT = `id, type, content, scope, relevance_score, source_tool, source_session,
+                metadata, created_at, updated_at, expires_at,
+                project_id, fingerprint, origin,
+                evidence_count, recurrence_count, last_verified_at, status, fix_args`;
+/**
+ * v0.5.0 (K5-008/009 / plan §5.6) — cached per-store probe for the 006-only
+ * `ignored` column (pre-006 DBs must not reference it). Shared by the
+ * retrieval filter, the row SELECT, and the save() ignored stamp.
+ */
+const ignoredColumnCache = new WeakMap();
+function hasIgnoredColumn(store) {
+    const cached = ignoredColumnCache.get(store);
+    if (cached !== undefined)
+        return cached;
+    try {
+        store.prepare("SELECT ignored FROM memories LIMIT 1").get();
+        ignoredColumnCache.set(store, true);
+        return true;
+    }
+    catch {
+        ignoredColumnCache.set(store, false);
+        return false;
+    }
+}
+/**
+ * v0.5.0 (K5-009 / plan §5.3) — the 006-only columns are appended when the
+ * migration has run (same probe as the `ignored = 0` retrieval filter).
+ */
+function rowSelect(store) {
+    return hasIgnoredColumn(store)
+        ? `${MEMORY_ROW_SELECT}, ignored, superseded_by,
+		   feedback_positive, feedback_negative`
+        : MEMORY_ROW_SELECT;
+}
 function mapRow(row, score) {
     const mem = {
         id: row.id,
@@ -67,11 +119,20 @@ function mapRow(row, score) {
         fingerprint: row.fingerprint ?? null,
         origin: row.origin ?? null,
         confidence: typeof row.evidence_count === "number"
-            ? Math.min(1, 0.5 + 0.1 * (row.evidence_count ?? 0))
+            ? computeConfidence(row.evidence_count ?? 0, row.recurrence_count ?? 0, row.feedback_positive ?? 0, row.feedback_negative ?? 0)
             : null,
         evidenceCount: row.evidence_count ?? null,
         lastVerifiedAt: row.last_verified_at ?? null,
         status: row.status ?? "active",
+        fixArgs: row.fix_args ?? null,
+        recurrenceCount: row.recurrence_count ?? null,
+        // v0.5.0 (K5-009 / plan §5.3, D5-07) — the human-verdict and
+        // supersession fields; absent on pre-006 rows.
+        ignored: row.ignored === undefined ? undefined : Boolean(row.ignored),
+        supersedes: row.superseded_by ?? null,
+        // v0.5.0 (K5-010 / plan §5.3) — human judgement counters.
+        feedbackPositive: row.feedback_positive ?? 0,
+        feedbackNegative: row.feedback_negative ?? 0,
     };
     if (score !== undefined) {
         if (!mem.metadata)
@@ -106,6 +167,29 @@ export class MemoryService {
     // so that Metrics can be added without changing the parameter order callers
     // have been using since v0.1.0.
     store;
+    // v0.4.0 (BUG-008) — cached column probe for pre-005 DBs (which lack
+    // `recurrence_count`); save() must not reference the column there.
+    hasRecurrenceColumn() {
+        if (this._hasRecurrenceColumn === undefined) {
+            try {
+                this.store
+                    .prepare("SELECT recurrence_count FROM memories LIMIT 1")
+                    .get();
+                this._hasRecurrenceColumn = true;
+            }
+            catch {
+                this._hasRecurrenceColumn = false;
+            }
+        }
+        return this._hasRecurrenceColumn;
+    }
+    _hasRecurrenceColumn;
+    // v0.5.0 (K5-008 / plan §5.6) — cached column probe for pre-006 DBs
+    // (which lack `ignored`); the retrieval filter must not reference the
+    // column there.
+    hasIgnoredColumn() {
+        return hasIgnoredColumn(this.store);
+    }
     save(input) {
         const scope = input.scope ?? "project";
         const relevanceScore = input.relevanceScore ?? 0.5;
@@ -131,29 +215,56 @@ export class MemoryService {
         if (scope === "session" && !input.expiresAt) {
             expiresAt = sqliteUtcNowPlusHours(SESSION_DEFAULT_TTL_HOURS);
         }
-        const id = uuidv7();
+        const id = input.id ?? uuidv7();
         // v0.3.0 (K3-014) — supersede model: when saving a decision/rule with
         // the same fingerprint as an existing active row, mark the old as
         // superseded and insert the fresh version as active.
+        // v0.4.0 (K4-011) — `memories_superseded` is only counted here,
+        // where a row is truly replaced; penalization of recurring
+        // reflectors no longer increments it.
+        // v0.5.0 (K5-013 / plan §5.5, D5-06) — the old row also records WHO
+        // superseded it (`superseded_by = <new id>`), giving status-based
+        // supersession a navigable audit trail. Guarded: pre-006 DBs lack
+        // the column (same migration as `ignored`).
         const supersedableTypes = ["decision", "rule"];
         if (fp !== null && supersedableTypes.includes(input.type)) {
+            const withSupersededBy = this.hasIgnoredColumn();
+            const setClause = withSupersededBy
+                ? "SET status = 'superseded', superseded_by = ?, updated_at = datetime('now')"
+                : "SET status = 'superseded', updated_at = datetime('now')";
             this.store
                 .prepare(`UPDATE memories
-					 SET status = 'superseded', updated_at = datetime('now')
+					 ${setClause}
 					 WHERE fingerprint = ?
 					   AND type = ?
 					   AND status = 'active'
 					   AND (project_id IS ? OR (project_id IS NULL AND ? IS NULL))`)
-                .run(fp, input.type, projectId, projectId);
+                .run(...(withSupersededBy
+                ? [id, fp, input.type, projectId, projectId]
+                : [fp, input.type, projectId, projectId]));
+            const after = this.store.prepare("SELECT changes() AS n").get();
+            if (after.n > 0) {
+                this.metrics?.incr("memories_superseded", 1);
+            }
         }
         try {
-            this.store
-                .prepare(`INSERT INTO memories
+            // v0.4.0 (BUG-008) — recurrence_count is only persisted when the
+            // column exists (migration 005); pre-005 DBs get the legacy shape.
+            const withRecurrence = this.hasRecurrenceColumn();
+            const insert = withRecurrence
+                ? `INSERT INTO memories
+             (id, type, content, scope, relevance_score, source_tool, source_session,
+              metadata, expires_at, project_id, fingerprint, origin,
+              evidence_count, last_verified_at, status, recurrence_count)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+                : `INSERT INTO memories
              (id, type, content, scope, relevance_score, source_tool, source_session,
               metadata, expires_at, project_id, fingerprint, origin,
               evidence_count, last_verified_at, status)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                .run(id, input.type, input.content, scope, relevanceScore, input.sourceTool ?? null, input.sourceSession ?? null, metadata, expiresAt, projectId, fp, origin, input.evidenceCount ?? 0, input.lastVerifiedAt ?? null, status);
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+            this.store
+                .prepare(insert)
+                .run(id, input.type, input.content, scope, relevanceScore, input.sourceTool ?? null, input.sourceSession ?? null, metadata, expiresAt, projectId, fp, origin, input.evidenceCount ?? 0, input.lastVerifiedAt ?? null, status, ...(withRecurrence ? [input.recurrenceCount ?? 0] : []));
             return id;
         }
         catch (err) {
@@ -185,14 +296,26 @@ export class MemoryService {
     }
     getById(id) {
         const row = this.store
-            .prepare(`SELECT id, type, content, scope, relevance_score, source_tool, source_session,
-                metadata, created_at, updated_at, expires_at,
-                project_id, fingerprint, origin,
-                evidence_count, last_verified_at, status
+            .prepare(`SELECT ${rowSelect(this.store)}
          FROM memories WHERE id = ?`)
             .get(id);
         return row ? mapRow(row) : null;
     }
+    /**
+     * v0.4.0 (K4-016) — most recent ACTIVE memory for a fingerprint,
+     * optionally filtered by type. Feeds the HITL suggestion lookup
+     * (most-recurred fingerprint → its pattern memory).
+     */
+    getByFingerprint(fingerprint, type) {
+        const row = this.store
+            .prepare(`SELECT ${rowSelect(this.store)}
+         FROM memories
+        WHERE fingerprint = ? AND status = 'active'
+          ${type ? "AND type = ?" : ""}
+        ORDER BY created_at DESC LIMIT 1`)
+            .get(...(type ? [fingerprint, type] : [fingerprint]));
+        return row ? mapRow(row) : null;
+    }
     update(id, fields) {
         const cols = [];
         const vals = [];
@@ -232,6 +355,13 @@ export class MemoryService {
             cols.push("status = ?");
             vals.push(fields.status);
         }
+        // v0.4.0 (BUG-008) — recurrence_count is writable so okf-import can
+        // restore negative evidence across a round-trip. Guarded by the
+        // caller (pre-005 DBs lack the column; update() throws).
+        if (fields.recurrenceCount !== undefined) {
+            cols.push("recurrence_count = ?");
+            vals.push(fields.recurrenceCount);
+        }
         if (cols.length === 0)
             return;
         cols.push("updated_at = datetime('now')");
@@ -261,6 +391,11 @@ export class MemoryService {
       JOIN memories m ON m.rowid = memories_fts.rowid
       WHERE memories_fts MATCH ?
         AND (m.expires_at IS NULL OR m.expires_at > datetime('now'))`;
+        // v0.5.0 (K5-011 / plan §5.6, D5-07) — ignored memories are hidden
+        // from kevin_query too (guarded for pre-006 DBs).
+        if (this.hasIgnoredColumn()) {
+            sql += "\n        AND m.ignored = 0";
+        }
         const params = [match];
         if (!input.includeSuperseded) {
             sql += "\n        AND m.status = 'active'";
@@ -284,27 +419,57 @@ export class MemoryService {
             .map((r) => mapRow(r, r.score))
             .filter((m) => !isNotSearchable(m))
             .filter((m) => crossProjectOn || m.projectId !== null || m.origin !== "imported");
-        return input.full === true ? memories : memories.map(toSlim);
+        return input.full === true
+            ? memories
+            : memories.map((m) => toSlim(m, input.evidence === true));
     }
     isCrossProjectEnabled() {
         try {
             const row = this.store
                 .prepare("SELECT value FROM kevin_settings WHERE key = 'cross_project_enabled'")
                 .get();
-            return (row?.value ?? 0) === 1;
+            // BUG-002 — the column stores TEXT ('0'/'1'); the old numeric
+            // comparison `=== 1` could never match '1'.
+            return (row?.value ?? "0") === "1";
         }
         catch {
             return false;
         }
     }
+    /**
+     * v0.4.0 (K4-012) — read a kevin_settings flag by key. Falls back to
+     * the caller-provided default when the key is missing or the table is
+     * unavailable (legacy DB without the settings table).
+     */
+    getSetting(key, fallback = "0") {
+        try {
+            const row = this.store
+                .prepare("SELECT value FROM kevin_settings WHERE key = ?")
+                .get(key);
+            return row?.value ?? fallback;
+        }
+        catch {
+            return fallback;
+        }
+    }
     loadAll(scope, includeSuperseded = false) {
         let sql = `
       SELECT id, type, content, scope, relevance_score, source_tool, source_session,
              metadata, created_at, updated_at, expires_at,
              project_id, fingerprint, origin,
-             evidence_count, last_verified_at, status
+             evidence_count, last_verified_at, status`;
+        // v0.5.0 (K5-009/010) — 006-only columns, appended when present.
+        if (this.hasIgnoredColumn()) {
+            sql += ", ignored, superseded_by, feedback_positive, feedback_negative";
+        }
+        sql += `
       FROM memories
       WHERE (expires_at IS NULL OR expires_at > datetime('now'))`;
+        // v0.5.0 (K5-008 / plan §5.6) — ignored memories are excluded from
+        // retrieval (human verdict, D5-07). Guarded for pre-006 DBs.
+        if (this.hasIgnoredColumn()) {
+            sql += "\n        AND ignored = 0";
+        }
         if (!includeSuperseded) {
             sql += "\n        AND status = 'active'";
         }
@@ -317,24 +482,32 @@ export class MemoryService {
         return this.store.prepare(sql).all(...params);
     }
     queryRelevant(text, scope, includeSuperseded = false) {
-        const tokens = stripUnbalancedQuotes(text.trim())
-            .split(/\s+/)
-            .filter((t) => t.length > 0)
-            .map((t) => `"${t.replace(/"/g, '""')}"`);
+        const tokens = tokenizeQuery(stripUnbalancedQuotes(text));
         if (tokens.length === 0)
             return [];
-        const match = tokens.join(" OR ");
+        const match = toMatchClause(tokens, " OR ");
         let sql = `
       SELECT m.id, m.type, m.content, m.scope, m.relevance_score,
              m.source_tool, m.source_session, m.metadata,
              m.created_at, m.updated_at, m.expires_at,
              m.project_id, m.fingerprint, m.origin,
-             m.evidence_count, m.last_verified_at, m.status,
+             m.evidence_count, m.last_verified_at, m.status`;
+        // v0.5.0 (K5-009/010) — 006-only columns, appended when present.
+        if (this.hasIgnoredColumn()) {
+            sql +=
+                ", m.ignored, m.superseded_by, m.feedback_positive, m.feedback_negative";
+        }
+        sql += `,
              bm25(memories_fts) AS score
       FROM memories_fts
       JOIN memories m ON m.rowid = memories_fts.rowid
       WHERE memories_fts MATCH ?
         AND (m.expires_at IS NULL OR m.expires_at > datetime('now'))`;
+        // v0.5.0 (K5-008 / plan §5.6) — ignored memories are excluded from
+        // retrieval (human verdict, D5-07). Guarded for pre-006 DBs.
+        if (this.hasIgnoredColumn()) {
+            sql += "\n        AND m.ignored = 0";
+        }
         if (!includeSuperseded) {
             sql += "\n        AND m.status = 'active'";
         }
@@ -354,6 +527,20 @@ export class MemoryService {
         const charBudget = maxTokens * 4;
         const scope = input.scope ?? "project";
         const includeSuperseded = input.includeSuperseded === true;
+        // v0.5.0 (K5-008 / plan §5.6, D5-10) — one clock per call and one
+        // read of the opt-in determinism flag. Retrieval then becomes a
+        // pure function of database state: recency decay is frozen at 1.0
+        // and the relevance bump is skipped regardless of the `bump`
+        // argument. The column is TEXT; compare against the string.
+        const now = input.now ?? new Date();
+        const deterministic = this.getSetting("deterministic_retrieval", "0") === "1";
+        // v0.5.0 (K5-008 / plan §5.6, D5-10) — DATE_NOW sentinel: in
+        // deterministic mode the wall clock is never read; every query sees
+        // the same fixed future instant, so ordering is a pure function of
+        // database content.
+        const clockMs = deterministic
+            ? new Date(DATE_NOW).getTime()
+            : now.getTime();
         let candidates;
         if (input.query && input.query.trim().length > 0) {
             candidates = this.queryRelevant(input.query, scope, includeSuperseded);
@@ -376,7 +563,7 @@ export class MemoryService {
         // v0.2.0 (K2-023) origin-aware rank: BM25 × origin-boost × recency-decay.
         // Tie-breakers preserve the v0.1.x spirit (errors/patterns before
         // context; newer before older when nothing else decides).
-        candidates.sort((a, b) => rankCompare(a, b));
+        candidates.sort((a, b) => rankCompare(a, b, clockMs, deterministic));
         const result = [];
         let used = 0;
         for (const mem of candidates) {
@@ -386,7 +573,11 @@ export class MemoryService {
             result.push(mem);
             used += len;
         }
-        if (result.length > 0) {
+        // v0.5.0 (K5-008 / D5-10) — the bump is part of the non-determinism
+        // this release makes optional: in deterministic mode it is skipped
+        // entirely so repeated queries return identical ranks and leave
+        // every relevance_score untouched.
+        if (result.length > 0 && !deterministic && input.bump !== false) {
             const bump = this.store.prepare("UPDATE memories SET relevance_score = MIN(?, relevance_score + ?) WHERE id = ?");
             this.store.transaction(() => {
                 for (const m of result)
@@ -395,6 +586,20 @@ export class MemoryService {
         }
         return result;
     }
+    /**
+     * v0.4.0 (BUG-016) — apply the K2-023 relevance bump to a fixed slice
+     * of ids, exactly once. Lets ContextInjector probe without mutating
+     * and still bump the slice it actually injects.
+     */
+    bumpRelevance(ids) {
+        if (ids.length === 0)
+            return;
+        const bump = this.store.prepare("UPDATE memories SET relevance_score = MIN(?, relevance_score + ?) WHERE id = ?");
+        this.store.transaction(() => {
+            for (const id of ids)
+                bump.run(RELEVANCE_MAX, RELEVANCE_BUMP, id);
+        });
+    }
     /**
      * v0.3.0 (K3-004) — Promote an error memory to a causal pattern.
      *
@@ -404,14 +609,29 @@ export class MemoryService {
      * or null when the source error is not eligible (missing fingerprint,
      * wrong type, or already promoted).
      */
-    promoteToPattern(errorId, evidenceCount) {
+    /**
+     * v0.4.0 (K4-009) — returns `{ id, created }` so callers can tell a
+     * newly-created pattern from an idempotent refresh.
+     */
+    promoteToPattern(errorId, evidenceCount, recurrenceCount = 0) {
         const error = this.getById(errorId);
         if (!error || error.type !== "error" || !error.fingerprint)
             return null;
-        const confidence = Math.min(1.0, 0.5 + 0.1 * evidenceCount);
+        // v0.4.0 (K4-010) — two-sided confidence: recurrence demotes the
+        // pattern's confidence.
+        const confidence = computeConfidence(evidenceCount, recurrenceCount);
         const now = new Date().toISOString();
         const summary = error.content.split("\n")[0].slice(0, 200);
-        const content = `Causal pattern: ${summary}\n\nEvidence: ${evidenceCount} confirmed fix(es)\nConfidence: ${(confidence * 100).toFixed(0)}%\n\nOriginal: ${error.content.slice(0, 1000)}`;
+        const base = `Causal pattern: ${summary}\n\nEvidence: ${evidenceCount} confirmed fix(es)\nConfidence: ${(confidence * 100).toFixed(0)}%\n\nOriginal: ${error.content.slice(0, 1000)}`;
+        // v0.4.0 (K4-014) — deterministic "Fixed by:" from the linked
+        // success call's args_summary (D4-07). The opt-in LLM phrasing
+        // (K4-015) runs later in CausalChain.onSessionIdle, never here and
+        // never on the failure hot path.
+        const fixLine = deterministicFixLine({
+            content: base,
+            fixArgs: error.fixArgs ?? null,
+        });
+        const content = fixLine ? `${base}\n${fixLine}` : base;
         // v0.3.0 fix (bug #4) — idempotent promotion: the supersede model
         // only covers decision/rule, so the old code inserted a duplicate
         // pattern on every subsequent session.idle with a new fix. When an
@@ -424,23 +644,34 @@ export class MemoryService {
 				   AND origin = 'causal' AND status = 'active'
 				 ORDER BY created_at DESC LIMIT 1`)
             .get(error.fingerprint);
+        let patternId;
         if (existing) {
             this.update(existing.id, { content, evidenceCount, lastVerifiedAt: now });
-            return existing.id;
-        }
-        return this.save({
-            type: "pattern",
-            content,
-            scope: "project",
-            origin: "causal",
-            sourceTool: error.sourceTool ?? undefined,
-            sourceSession: error.sourceSession ?? undefined,
-            fingerprint: error.fingerprint,
-            evidenceCount,
-            lastVerifiedAt: now,
-            status: "active",
-            projectId: error.projectId ?? undefined,
-        });
+            patternId = existing.id;
+        }
+        else {
+            patternId = this.save({
+                type: "pattern",
+                content,
+                scope: "project",
+                origin: "causal",
+                sourceTool: error.sourceTool ?? undefined,
+                sourceSession: error.sourceSession ?? undefined,
+                fingerprint: error.fingerprint,
+                evidenceCount,
+                lastVerifiedAt: now,
+                status: "active",
+                projectId: error.projectId ?? undefined,
+            });
+        }
+        // v0.4.0 (K4-010) — persist the recurrence count on the pattern row
+        // so mapRow (and kevin_why) recompute the SAME demoted confidence.
+        // v0.4.0 (K4-014) — persist fix_args too: the pattern's "Fixed by:"
+        // raw material travels with the row for kevin_why/HITL (K4-016/020).
+        this.store
+            .prepare("UPDATE memories SET recurrence_count = ?, fix_args = ? WHERE id = ?")
+            .run(recurrenceCount, error.fixArgs ?? null, patternId);
+        return { id: patternId, created: !existing };
     }
     /**
      * v0.2.0 (K2-026) — Feedback loop positive half (plan §B6.10 / D2-10).
@@ -541,9 +772,16 @@ export class MemoryService {
 			   AND (error_fingerprint = ? OR fingerprint = ?)
 			   AND (project_id IS ? OR (project_id IS NULL AND ? IS NULL))
 			   AND (? IS NULL OR id <> ?)`);
+        const settledCheck = this.store.prepare(`SELECT 1 FROM kevin_injections
+			  WHERE session_id = ? AND memory_id = ? AND outcome = 'ineffective'
+			  LIMIT 1`);
         const penalizeOne = this.store.prepare(`UPDATE memories
 			 SET relevance_score = MAX(0, relevance_score - ?),
-			     evidence_count = evidence_count + 1,
+			     recurrence_count = recurrence_count + 1,
+			     last_verified_at = datetime('now')
+			 WHERE id = ?`);
+        const penalizeRelevanceOnly = this.store.prepare(`UPDATE memories
+			 SET relevance_score = MAX(0, relevance_score - ?),
 			     last_verified_at = datetime('now')
 			 WHERE id = ?`);
         let penalized = 0;
@@ -553,9 +791,35 @@ export class MemoryService {
                 const row = recurrenceCheck.get(sessionId, l.fingerprint, l.fingerprint, l.project_id, l.project_id, originCallId, originCallId);
                 const c = row?.c ?? 0;
                 if (c > 0) {
-                    penalizeOne.run(RELEVANCE_PENALTY, l.id);
+                    // v0.4.0 (K4-025) — no double-charge: when the
+                    // session's injection of this memory was already
+                    // settled `ineffective`, `InjectionLedger.settle`
+                    // charged recurrence_count (K4-007) and this pass
+                    // only applies the relevance penalty. The +1 charge
+                    // below is the pre-ledger path (K4-011) for memories
+                    // that were never injected this session.
+                    const settled = settledCheck.get(sessionId, l.id);
+                    if (settled) {
+                        penalizeRelevanceOnly.run(RELEVANCE_PENALTY, l.id);
+                    }
+                    else {
+                        // v0.4.0 (K4-011) — recurrence is negative evidence:
+                        // it bumps `recurrence_count`, NOT `evidence_count`
+                        // (the old code counted recurrence as positive
+                        // evidence). No `memories_superseded` increment here —
+                        // supersede is only counted when a decision/rule is
+                        // truly replaced (see save()).
+                        penalizeOne.run(RELEVANCE_PENALTY, l.id);
+                        // v0.4.0 (K4-025 / plan §5.1 rule 4, D4-06) — same
+                        // recurrence-expels rule the settle enforces: at
+                        // `recurrence_count >= 3` the error lesson is demoted
+                        // to `status='stale'`.
+                        this.store
+                            .prepare(`UPDATE memories SET status = 'stale'
+								  WHERE id = ? AND recurrence_count >= 3`)
+                            .run(l.id);
+                    }
                     penalized += 1;
-                    this.metrics?.incr("memories_superseded", 1);
                 }
             }
         });
@@ -617,19 +881,22 @@ export function countSupersedeCandidates(store, type, fingerprint, projectId) {
         .get(fingerprint, projectId, projectId);
     return row?.c ?? 0;
 }
-function rankScore(mem) {
+function rankScore(mem, nowMs, deterministic) {
     // FTS5 bm25 returns a negative score (more negative = better match).
     // For non-FTS rows (loadAll path), fall back to -relevance_score so
     // higher-relevance memories also come first under the same sign convention.
     const rawScore = mem.metadata?.score;
     const base = typeof rawScore === "number" ? rawScore : -mem.relevanceScore;
-    const ageDays = Math.max(0, (Date.now() - sqliteUtcToMs(mem.createdAt)) / 86_400_000);
-    const recencyDecay = RECENCY_DECAY_PER_DAY ** ageDays;
+    const ageDays = Math.max(0, (nowMs - sqliteUtcToMs(mem.createdAt)) / 86_400_000);
+    // v0.5.0 (K5-008 / plan §5.6, D5-10) — deterministic retrieval freezes
+    // the recency factor at 1.0 so ordering depends only on content
+    // relevance and origin boost, never on the wall clock.
+    const recencyDecay = deterministic ? 1 : RECENCY_DECAY_PER_DAY ** ageDays;
     return base * originBoost(mem) * recencyDecay;
 }
-function rankCompare(a, b) {
-    const ra = rankScore(a);
-    const rb = rankScore(b);
+function rankCompare(a, b, nowMs, deterministic) {
+    const ra = rankScore(a, nowMs, deterministic);
+    const rb = rankScore(b, nowMs, deterministic);
     if (ra !== rb)
         return ra - rb; // ascending: most negative (best) first
     if (TYPE_PRIORITY[a.type] !== TYPE_PRIORITY[b.type]) {