akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/commands/improve/memory/memory-belief.js

@@ -27,9 +27,7 @@
  * - Zep / Graphiti (arXiv:2501.13956 §3) — unified belief-revision pipeline
  * - MemOS (arXiv:2507.03724) — formal archive/merge/transition with shared state model
  */
-import fs from "node:fs";
-import { assembleAsset } from "../../../core/asset/asset-serialize.js";
-import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { mutateFrontmatter } from "../../../core/asset/frontmatter.js";
 // ── Contradiction edge writer ─────────────────────────────────────────────────
 /**
  * Write `contradictedBy` and `beliefState: contradicted` edges to a memory
@@ -47,16 +45,17 @@ import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
  * @param contradictedByRef - The ref that contradicts this memory.
  */
 export function writeContradictEdge(filePath, contradictedByRef) {
-    const raw = fs.readFileSync(filePath, "utf8");
-    const parsed = parseFrontmatter(raw);
-    const existing = Array.isArray(parsed.data.contradictedBy) ? parsed.data.contradictedBy : [];
-    if (existing.includes(contradictedByRef))
-        return; // Already written — idempotent.
-    const nextContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
-    const nextFrontmatter = {
-        ...parsed.data,
-        contradictedBy: nextContradictedBy,
-        beliefState: "contradicted",
-    };
-    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+    mutateFrontmatter(filePath, (parsed) => {
+        const existing = Array.isArray(parsed.data.contradictedBy)
+            ? parsed.data.contradictedBy
+            : [];
+        if (existing.includes(contradictedByRef))
+            return null; // Already written — idempotent.
+        const nextContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
+        return {
+            ...parsed.data,
+            contradictedBy: nextContradictedBy,
+            beliefState: "contradicted",
+        };
+    });
 }

package/dist/commands/improve/memory/memory-contradiction-detect.js

@@ -35,8 +35,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { assembleAsset } from "../../../core/asset/asset-serialize.js";
-import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import contradictionJudgeTemplate from "../../../assets/prompts/contradiction-judge.md" with { type: "text" };
+import { mutateFrontmatter, parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { getDefaultLlmConfig } from "../../../core/config/config.js";
 import { chatCompletion, parseEmbeddedJsonResponse } from "../../../llm/client.js";
 import { tryLlmFeature } from "../../../llm/feature-gate.js";
@@ -51,6 +51,13 @@ const MAX_FAMILY_SIZE = 8;
  * families. Prevents runaway LLM usage on stashes with many memories.
  */
 const MAX_PAIRS_PER_RUN = 20;
+/**
+ * Minimum confidence required to write a contradiction edge. Below this
+ * threshold the LLM may be flagging topic-overlap rather than genuine logical
+ * exclusivity (investigation 2026-06-18). Absent confidence fields default to
+ * 1.0 for backward compatibility with older judge responses.
+ */
+const CONTRADICT_CONFIDENCE_THRESHOLD = 0.92;
 /**
  * Truncation limit for memory body content sent to the LLM judge.
  * Keeps prompts compact while preserving the key factual claims.
@@ -58,34 +65,13 @@ const MAX_PAIRS_PER_RUN = 20;
 const BODY_TRUNCATION = 800;
 // ── Prompt builder ────────────────────────────────────────────────────────────
 function buildContradictionJudgePrompt(a, b) {
-    return [
-        "You are evaluating two derived memory entries to determine if they contain",
-        "directly contradictory factual claims about the same subject.",
-        "",
-        "Memory A:",
-        `Ref: ${a.ref}`,
-        `Description: ${a.description || "(none)"}`,
-        "Content:",
-        "```",
-        a.body.slice(0, BODY_TRUNCATION),
-        "```",
-        "",
-        "Memory B:",
-        `Ref: ${b.ref}`,
-        `Description: ${b.description || "(none)"}`,
-        "Content:",
-        "```",
-        b.body.slice(0, BODY_TRUNCATION),
-        "```",
-        "",
-        "Answer ONLY with valid JSON — no prose, no code fences:",
-        '{"contradicts": true|false, "reason": "<one sentence explaining why or why not>"}',
-        "",
-        "A contradiction means the memories make mutually exclusive factual claims about the",
-        "same topic (e.g. Memory A says 'always use VPN' while Memory B says 'VPN is optional').",
-        "If the memories are complementary, about different topics, or one supersedes the other",
-        "without direct conflict, return false.",
-    ].join("\n");
+    return contradictionJudgeTemplate
+        .replace("{{A_REF}}", a.ref)
+        .replace("{{A_DESCRIPTION}}", a.description || "(none)")
+        .replace("{{A_BODY}}", a.body.slice(0, BODY_TRUNCATION))
+        .replace("{{B_REF}}", b.ref)
+        .replace("{{B_DESCRIPTION}}", b.description || "(none)")
+        .replace("{{B_BODY}}", b.body.slice(0, BODY_TRUNCATION));
 }
 // ── Filesystem helpers ────────────────────────────────────────────────────────
 function* walkMarkdownFilesLocal(root) {
@@ -139,19 +125,42 @@ function resolveParentRef(filePath, frontmatter, memoriesRootDir) {
  */
 /** Returns true if the edge was newly written, false if it already existed. */
 function writeContradictedByEdge(filePath, contradictedByRef) {
-    const raw = fs.readFileSync(filePath, "utf8");
-    const parsed = parseFrontmatter(raw);
-    const existing = Array.isArray(parsed.data.contradictedBy) ? parsed.data.contradictedBy : [];
-    if (existing.includes(contradictedByRef))
-        return false; // Edge already written.
-    const updatedContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
-    const nextFrontmatter = {
-        ...parsed.data,
-        contradictedBy: updatedContradictedBy,
-        beliefState: "contradicted",
-    };
-    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
-    return true;
+    return mutateFrontmatter(filePath, (parsed) => {
+        const existing = Array.isArray(parsed.data.contradictedBy)
+            ? parsed.data.contradictedBy
+            : [];
+        if (existing.includes(contradictedByRef))
+            return null; // Edge already written.
+        const updatedContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
+        return {
+            ...parsed.data,
+            contradictedBy: updatedContradictedBy,
+            beliefState: "contradicted",
+        };
+    });
+}
+/**
+ * Deterministically pick, for a confirmed-contradiction pair, the LOSER memory
+ * that receives the single directed `contradictedBy` edge (SCC-resolved to
+ * `contradicted`) and the WINNER ref that survives as the current belief.
+ *
+ * A SINGLE directed edge is essential. Writing mutual A↔B edges forms a 2-cycle
+ * that {@link resolveFamilyContradictions} collapses into one strongly-connected
+ * SINK component and refreshes BOTH members back to active — erasing the
+ * contradiction on every run (the self-erasing bug this fix removes).
+ *
+ * Direction = lexicographic ref order: the ref that sorts LATER is the loser.
+ * This is a **total order** over the family's (distinct) refs, so the induced
+ * edges are always acyclic — a family of any size resolves to a DAG with a
+ * single sink, never a cycle that the resolver would refresh back to active.
+ * It is also immutable across runs (unlike file mtime, which the resolver
+ * bumps when it rewrites loser files), so detection is idempotent. Ref order
+ * carries no recency meaning — no derived-memory writer sets a `createdAt`/
+ * timestamp today — but the mechanism only needs a stable, acyclic direction;
+ * eliminating worst-case self-erasure, not ranking by recency, is the goal.
+ */
+function pickContradictionLoser(a, b) {
+    return a.ref < b.ref ? { loser: b, winnerRef: a.ref } : { loser: a, winnerRef: b.ref };
 }
 // ── Main entry point ──────────────────────────────────────────────────────────
 /**
@@ -222,18 +231,22 @@ export async function detectAndWriteContradictions(stashDir, config, chat = chat
                 const b = family[j];
                 if (!a || !b)
                     continue;
-                // Skip pairs where edges already exist in BOTH directions (no new information).
-                const aRaw = fs.readFileSync(a.filePath, "utf8");
-                const aParsed = parseFrontmatter(aRaw);
-                const aCB = Array.isArray(aParsed.data.contradictedBy)
-                    ? aParsed.data.contradictedBy
-                    : [];
-                const bRaw = fs.readFileSync(b.filePath, "utf8");
-                const bParsed = parseFrontmatter(bRaw);
-                const bCB = Array.isArray(bParsed.data.contradictedBy)
-                    ? bParsed.data.contradictedBy
-                    : [];
-                if (aCB.includes(b.ref) && bCB.includes(a.ref))
+                // Resolve the directed edge up front (independent of the judge — it is
+                // decided by lexicographic ref order). Skip when that single loser→winner
+                // edge already exists (no new information; avoids re-judging resolved
+                // pairs across runs).
+                //
+                // Legacy mutual A↔B edges written by the pre-fix pass self-heal: the
+                // skip fires this run, but the SCC resolver treats the 2-cycle as a sink
+                // and refreshes both to active — DELETING both `contradictedBy` arrays
+                // (memory-improve.ts persistBeliefStateTransition). The next detection
+                // run then sees no edge, re-judges, and writes the single canonical edge.
+                const aParsed = parseFrontmatter(fs.readFileSync(a.filePath, "utf8"));
+                const bParsed = parseFrontmatter(fs.readFileSync(b.filePath, "utf8"));
+                const { loser, winnerRef } = pickContradictionLoser(a, b);
+                const loserData = loser === a ? aParsed.data : bParsed.data;
+                const loserCB = Array.isArray(loserData.contradictedBy) ? loserData.contradictedBy : [];
+                if (loserCB.includes(winnerRef))
                     continue;
                 const prompt = buildContradictionJudgePrompt(a, b);
                 const judgeResult = await tryLlmFeature("memory_contradiction_detection", config, async () => {
@@ -256,14 +269,24 @@ export async function detectAndWriteContradictions(stashDir, config, chat = chat
                 }
                 if (!parsed?.contradicts)
                     continue;
-                // Write contradiction edges: both members get contradictedBy pointing to each other.
+                // Confidence gate: absent field defaults to 1.0 (backward compat with
+                // pre-confidence responses). Do NOT default to 0 — that would silently
+                // disable all detection during the rollout period.
+                const confidence = typeof parsed.confidence === "number" ? parsed.confidence : 1.0;
+                if (confidence < CONTRADICT_CONFIDENCE_THRESHOLD) {
+                    result.warnings.push(`Pair ${a.ref} / ${b.ref}: confidence ${confidence.toFixed(2)} below ${CONTRADICT_CONFIDENCE_THRESHOLD} threshold — skipped.`);
+                    continue;
+                }
+                // Write a SINGLE directed contradiction edge: the losing (older) memory
+                // gets `contradictedBy` pointing to the winner. A mutual A↔B pair forms
+                // a 2-cycle that the SCC resolver refreshes back to active, erasing the
+                // contradiction every run (see pickContradictionLoser).
                 try {
-                    const wroteA = writeContradictedByEdge(a.filePath, b.ref);
-                    const wroteB = writeContradictedByEdge(b.filePath, a.ref);
-                    result.edgesWritten += (wroteA ? 1 : 0) + (wroteB ? 1 : 0);
+                    const wrote = writeContradictedByEdge(loser.filePath, winnerRef);
+                    result.edgesWritten += wrote ? 1 : 0;
                 }
                 catch (err) {
-                    result.warnings.push(`Failed to write contradiction edge ${a.ref} <-> ${b.ref}: ${err instanceof Error ? err.message : String(err)}`);
+                    result.warnings.push(`Failed to write contradiction edge ${loser.ref} -> ${winnerRef}: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
             if (totalPairsChecked >= MAX_PAIRS_PER_RUN)

package/dist/commands/improve/memory/memory-improve.js

@@ -5,8 +5,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { makeAssetRef, parseAssetRef } from "../../../core/asset/asset-ref.js";
 import { assembleAsset } from "../../../core/asset/asset-serialize.js";
-import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
-import { firstString, groupBy, stringArray } from "../../../core/common.js";
+import { mutateFrontmatter, parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { asNonEmptyString, groupBy, stringArray } from "../../../core/common.js";
 const DERIVED_SUFFIX = ".derived";
 export function analyzeMemoryCleanup(stashDir, options = {}) {
     const records = collectDerivedMemories(stashDir, options.parentRef);
@@ -491,27 +491,27 @@ function archiveCleanupCandidate(stashDir, candidate, filePath) {
     };
 }
 function persistBeliefStateTransition(filePath, transition) {
-    const raw = fs.readFileSync(filePath, "utf8");
-    const parsed = parseFrontmatter(raw);
-    const nextFrontmatter = {
-        ...parsed.data,
-        beliefState: transition.toState,
-    };
-    const currentBeliefRefs = [...new Set(transition.currentBeliefRefs ?? [])].sort();
-    if (transition.toState === "contradicted") {
-        nextFrontmatter.contradictedBy = [...currentBeliefRefs];
-    }
-    else {
-        delete nextFrontmatter.contradictedBy;
-        if (parsed.data.supersededBy !== undefined && refArray(parsed.data.supersededBy).length === 0) {
-            delete nextFrontmatter.supersededBy;
+    mutateFrontmatter(filePath, (parsed) => {
+        const nextFrontmatter = {
+            ...parsed.data,
+            beliefState: transition.toState,
+        };
+        const currentBeliefRefs = [...new Set(transition.currentBeliefRefs ?? [])].sort();
+        if (transition.toState === "contradicted") {
+            nextFrontmatter.contradictedBy = [...currentBeliefRefs];
         }
-    }
-    if (currentBeliefRefs.length > 0)
-        nextFrontmatter.currentBeliefRefs = [...currentBeliefRefs];
-    else
-        delete nextFrontmatter.currentBeliefRefs;
-    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+        else {
+            delete nextFrontmatter.contradictedBy;
+            if (parsed.data.supersededBy !== undefined && refArray(parsed.data.supersededBy).length === 0) {
+                delete nextFrontmatter.supersededBy;
+            }
+        }
+        if (currentBeliefRefs.length > 0)
+            nextFrontmatter.currentBeliefRefs = [...currentBeliefRefs];
+        else
+            delete nextFrontmatter.currentBeliefRefs;
+        return nextFrontmatter;
+    });
 }
 function appendBeliefStateTransitionLog(stashDir, transitions) {
     const logDir = path.join(stashDir, ".akm", "memory-cleanup");
@@ -580,8 +580,8 @@ function collectDerivedMemories(stashDir, parentRefFilter) {
             continue;
         if (!isDerivedMemory(name, parsed.data))
             continue;
-        const title = firstString(parsed.data.title) ?? extractHeading(parsed.content) ?? "";
-        const description = firstString(parsed.data.description) ?? "";
+        const title = asNonEmptyString(parsed.data.title) ?? extractHeading(parsed.content) ?? "";
+        const description = asNonEmptyString(parsed.data.description) ?? "";
         const tags = stringArray(parsed.data.tags);
         const searchHints = stringArray(parsed.data.searchHints);
         const body = parsed.content.trim();
@@ -637,7 +637,7 @@ function isFrozenHistoricalBeliefState(state) {
     return state === "deprecated";
 }
 function resolveBeliefState(frontmatter) {
-    const explicit = firstString(frontmatter.beliefState);
+    const explicit = asNonEmptyString(frontmatter.beliefState);
     if (explicit === "active" ||
         explicit === "asserted" ||
         explicit === "deprecated" ||
@@ -651,10 +651,10 @@ function isDerivedMemory(name, frontmatter) {
     return frontmatter.inferred === true || name.endsWith(DERIVED_SUFFIX);
 }
 function resolveParentRef(name, frontmatter) {
-    const fromSource = parseMemoryRef(firstString(frontmatter.source));
+    const fromSource = parseMemoryRef(asNonEmptyString(frontmatter.source));
     if (fromSource)
         return fromSource;
-    const derivedFrom = firstString(frontmatter.derivedFrom);
+    const derivedFrom = asNonEmptyString(frontmatter.derivedFrom);
     if (derivedFrom)
         return makeAssetRef("memory", derivedFrom);
     if (name.endsWith(DERIVED_SUFFIX)) {

package/dist/commands/improve/outcome-loop.js

@@ -0,0 +1,270 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * EMA decay factor for the expected-retrieval rolling mean (α).
+ * New expected = α × new_count + (1−α) × old_expected.
+ * At α = 0.3 the window is ≈ 3 cycles.
+ */
+export const OUTCOME_EMA_ALPHA = 0.3;
+/**
+ * Maximum K improve cycles for the eligibility-trace window. Retrievals older
+ * than K cycles contribute via the EMA decay naturally (they are already baked
+ * into `expected_retrieval_rate`).
+ */
+export const OUTCOME_TRACE_CYCLES = 5;
+/**
+ * Warm-start cap: the maximum `outcome_score` a brand-new row can be seeded with
+ * (from the utility EMA). Prevents a `[0,1]`-range utility value from generating
+ * a score that the first negative delta could catastrophically invert. Clipped to
+ * the maximum plausible first differential update: `max(0, 1 − 0) = 1`, so cap
+ * at a modest 0.3 to avoid spurious rank-flip on first cycle.
+ */
+export const WARM_START_CAP = 0.3;
+/**
+ * Penalty cap: the minimum outcome_score is capped at this value so a single
+ * very-negative run can't send the score to −∞.
+ */
+export const OUTCOME_SCORE_MIN = -1.0;
+/**
+ * Saturation ceiling: the maximum outcome_score. Biological RPE saturates —
+ * a fully predicted reward produces zero response, not an ever-growing one —
+ * so a long-lived popular asset must not accrue unbounded outcome mass that
+ * would dominate ranking once the outcome weight is enabled (analysis G2).
+ * 1.5 comfortably exceeds the max plausible single-cycle raw update while
+ * keeping the normalised outcomeSalience spread meaningful.
+ */
+export const OUTCOME_SCORE_MAX = 1.5;
+/**
+ * Diversity floor: `outcomeSalience` for any asset is at least this fraction
+ * of the maximum observed `outcome_score` in the table, so rare-but-correct
+ * assets cannot be permanently outcompeted. 0 = disabled (pure competition).
+ */
+export const DIVERSITY_FLOOR_FRACTION = 0.1;
+/**
+ * Default review_pressure increment per negative-feedback retrieval cycle.
+ * Each cycle where negative_feedback_count > 0, pressure increases by this
+ * much (and decreases by REVIEW_PRESSURE_DECAY if no new negatives).
+ */
+export const REVIEW_PRESSURE_INCREMENT = 1;
+/**
+ * Decay per non-negative cycle. Keeps review_pressure from accumulating forever
+ * when an asset's quality problems are addressed and feedback turns positive.
+ */
+export const REVIEW_PRESSURE_DECAY = 1;
+/**
+ * Upsert one asset's outcome row.
+ *
+ * On first call for a ref (no prior row): warm-starts from `utilityScore`.
+ * On subsequent calls: applies the differential update formula.
+ *
+ * Returns the resulting `outcome_score` and `review_pressure` so the caller
+ * can pass them to `computeSalience` without a second read.
+ */
+export function updateAssetOutcome(db, inputs) {
+    const now = inputs.now ?? Date.now();
+    const valence = inputs.valence ?? 0;
+    // Fetch existing row (or undefined for first insert).
+    const existing = getAssetOutcome(db, inputs.ref);
+    const isNewRow = existing === undefined;
+    let outcomeScore;
+    let reviewPressure;
+    let expectedRetrievalRate;
+    if (isNewRow) {
+        // ── Warm-start ─────────────────────────────────────────────────────────
+        // Seed from utility EMA, clipped to [0, WARM_START_CAP].
+        // The warm-start is a non-negative seed; the first real differential update
+        // will adjust it up or down from there.
+        const seedScore = Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
+        outcomeScore = seedScore;
+        reviewPressure = 0;
+        // Seed expected_retrieval_rate = 0 (no delta history yet).
+        // Seeding with currentRetrievalCount would produce a large spurious negative
+        // prediction error on the first real cycle (delta ≪ cumulative count).
+        expectedRetrievalRate = 0;
+    }
+    else {
+        // ── Differential update ────────────────────────────────────────────────
+        //
+        // retrieval_delta = current − stored (non-negative — we never go backwards)
+        const retrievalDelta = Math.max(0, inputs.currentRetrievalCount - existing.retrieval_count);
+        // Differential prediction-error term:
+        // outcome = (retrieval_delta − expected_delta) + valence
+        //
+        // Prediction error is computed against the PRIOR stored EMA (before folding
+        // in this cycle's observation), so the current delta cannot leak into its own
+        // expectation. Negative values are intentional — they signal below-average cycles.
+        const expectedDelta = existing.expected_retrieval_rate;
+        const predictionError = retrievalDelta - expectedDelta;
+        // Advance the EMA over the OBSERVED delta (not the cumulative count).
+        // expected' = α × delta + (1−α) × prior_expected
+        expectedRetrievalRate =
+            OUTCOME_EMA_ALPHA * retrievalDelta + (1 - OUTCOME_EMA_ALPHA) * existing.expected_retrieval_rate;
+        // Running sum (EMA approach): new score = α × update + (1−α) × old
+        // so the score tracks the moving signal, not the cumulative sum.
+        const rawUpdate = predictionError + valence;
+        const newScore = OUTCOME_EMA_ALPHA * rawUpdate + (1 - OUTCOME_EMA_ALPHA) * existing.outcome_score;
+        // Clip to [OUTCOME_SCORE_MIN, OUTCOME_SCORE_MAX] — the ceiling is the RPE
+        // saturation analog (G2): without it, long-lived popular assets accumulate
+        // unbounded positive mass (live max was 3.13) and would dominate rank_score
+        // the moment the outcome weight is enabled. Stored legacy scores above the
+        // ceiling converge back under it on their next differential update.
+        outcomeScore = Math.min(OUTCOME_SCORE_MAX, Math.max(OUTCOME_SCORE_MIN, newScore));
+        // ── review_pressure (#613) ─────────────────────────────────────────────
+        // New negatives this cycle.
+        const newNegatives = Math.max(0, inputs.negativeFeedbackCount - existing.negative_feedback_count);
+        if (newNegatives > 0) {
+            reviewPressure = Math.min(10, existing.review_pressure + REVIEW_PRESSURE_INCREMENT * newNegatives);
+        }
+        else {
+            // Decay when no new negatives.
+            reviewPressure = Math.max(0, existing.review_pressure - REVIEW_PRESSURE_DECAY);
+        }
+    }
+    // Upsert the row.
+    db.prepare(`INSERT INTO asset_outcome
+       (asset_ref, last_retrieved_at, retrieval_count, expected_retrieval_rate,
+        negative_feedback_count, accepted_change_count, review_pressure,
+        outcome_score, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(asset_ref) DO UPDATE SET
+       last_retrieved_at      = excluded.last_retrieved_at,
+       retrieval_count        = excluded.retrieval_count,
+       expected_retrieval_rate= excluded.expected_retrieval_rate,
+       negative_feedback_count= excluded.negative_feedback_count,
+       accepted_change_count  = excluded.accepted_change_count,
+       review_pressure        = excluded.review_pressure,
+       outcome_score          = excluded.outcome_score,
+       updated_at             = excluded.updated_at`).run(inputs.ref, inputs.lastRetrievedAt, inputs.currentRetrievalCount, expectedRetrievalRate, inputs.negativeFeedbackCount, inputs.acceptedChangeCount, reviewPressure, outcomeScore, now);
+    return { outcomeScore, reviewPressure, isNewRow };
+}
+// ── Reader ────────────────────────────────────────────────────────────────────
+/**
+ * Load the outcome row for one asset, or `undefined` if not yet written.
+ */
+export function getAssetOutcome(db, ref) {
+    const row = db
+        .prepare(`SELECT asset_ref, last_retrieved_at, retrieval_count, expected_retrieval_rate,
+              negative_feedback_count, accepted_change_count, review_pressure,
+              outcome_score, updated_at
+       FROM asset_outcome WHERE asset_ref = ?`)
+        .get(ref);
+    return row == null ? undefined : row;
+}
+/**
+ * Load ALL asset_outcome rows. Used for the proxy-adequacy tripwire computation.
+ */
+export function getAllAssetOutcomes(db) {
+    return db
+        .prepare(`SELECT asset_ref, last_retrieved_at, retrieval_count, expected_retrieval_rate,
+              negative_feedback_count, accepted_change_count, review_pressure,
+              outcome_score, updated_at
+       FROM asset_outcome ORDER BY asset_ref`)
+        .all();
+}
+/**
+ * Build a Map<ref, outcome_score> for a set of refs in one query.
+ * Used by `salience.ts` to populate `outcomeSalience`.
+ */
+export function getOutcomeScoresByRef(db, refs) {
+    const result = new Map();
+    if (refs.length === 0)
+        return result;
+    const CHUNK = 500;
+    for (let i = 0; i < refs.length; i += CHUNK) {
+        const chunk = refs.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT asset_ref, outcome_score FROM asset_outcome WHERE asset_ref IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            result.set(row.asset_ref, row.outcome_score);
+        }
+    }
+    return result;
+}
+// ── outcomeSalience projection ────────────────────────────────────────────────
+/**
+ * Convert a raw `outcome_score` (differential, may be negative) to a
+ * `outcomeSalience` value in [0, 1] suitable for use in the salience projection.
+ *
+ * Approach:
+ *   1. Clip negative scores to 0 (a negative outcome just means "below expected",
+ *      not "irrelevant"; it should not harm the base retrieval/encoding ranking).
+ *   2. Apply the diversity floor so rare-but-correct assets always retain a
+ *      minimum `outcomeSalience` relative to the stash-wide maximum.
+ *   3. Normalise by `maxScore` (the stash-wide max outcome_score) so the term
+ *      lives in [0, 1]. When maxScore ≤ 0 (all seeds, nothing observed yet),
+ *      return the floor (or 0 if DIVERSITY_FLOOR_FRACTION = 0).
+ *
+ * @param outcomeScore - Raw outcome_score from asset_outcome.
+ * @param maxScore     - Maximum outcome_score across ALL rows (≥ 0 after clip).
+ *                       Callers must compute this once per batch and pass it in.
+ */
+export function outcomeScoreToSalience(outcomeScore, maxScore) {
+    const clipped = Math.max(0, outcomeScore);
+    if (maxScore <= 0) {
+        // No positive scores observed yet — return diversity floor.
+        return DIVERSITY_FLOOR_FRACTION;
+    }
+    const normalised = clipped / maxScore;
+    // Apply diversity floor.
+    return Math.max(DIVERSITY_FLOOR_FRACTION, normalised);
+}
+// ── Proxy-adequacy tripwire ───────────────────────────────────────────────────
+/**
+ * Dead-proxy threshold: |corr| below this means outcome_score carries no
+ * information about improvement need (pure noise).
+ */
+export const PROXY_DEAD_CORR_THRESHOLD = 0.1;
+/**
+ * Minimum sample size before the dead-proxy check fires. Below this, a
+ * near-zero correlation is indistinguishable from small-sample noise.
+ */
+export const PROXY_DEAD_MIN_N = 500;
+/**
+ * Compute `corr(outcome_score, accepted_change_rate)` across all asset_outcome
+ * rows. Returns `{correlation: NaN, n, isInverted: false}` when there is
+ * insufficient data (fewer than 3 rows or zero variance in either variable).
+ *
+ * A NEGATIVE correlation means: assets with a HIGH outcome_score have a LOW
+ * accepted_change_rate — i.e. the assets the proxy rates as "doing well"
+ * (frequently retrieved) are precisely the ones that rarely yield an accepted
+ * improvement. That inverts the proxy: high outcome_score ≠ "doing well", so the
+ * coarse retrieval-delta signal is no longer trustworthy and the 0.10+ rich
+ * signal is due. (`isInverted = correlation < -0.3`.)
+ */
+export function computeProxyAdequacy(rows) {
+    const n = rows.length;
+    if (n < 3)
+        return { correlation: Number.NaN, n, isInverted: false, isDead: false };
+    // accepted_change_rate per row.
+    const xs = rows.map((r) => r.outcome_score);
+    const ys = rows.map((r) => r.accepted_change_count / Math.max(1, r.retrieval_count));
+    const meanX = xs.reduce((a, b) => a + b, 0) / n;
+    const meanY = ys.reduce((a, b) => a + b, 0) / n;
+    let covXY = 0;
+    let varX = 0;
+    let varY = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = xs[i] - meanX;
+        const dy = ys[i] - meanY;
+        covXY += dx * dy;
+        varX += dx * dx;
+        varY += dy * dy;
+    }
+    covXY /= n;
+    varX /= n;
+    varY /= n;
+    const denom = Math.sqrt(varX) * Math.sqrt(varY);
+    if (denom < 1e-12)
+        return { correlation: Number.NaN, n, isInverted: false, isDead: false };
+    const correlation = covXY / denom;
+    // Inverted proxy: negative correlation between outcome and accepted_change_rate
+    // means high-outcome assets are also high-need — the opposite of "useful".
+    const isInverted = correlation < -0.3;
+    // Dead proxy: near-zero correlation at scale — the score is noise.
+    const isDead = n >= PROXY_DEAD_MIN_N && Math.abs(correlation) < PROXY_DEAD_CORR_THRESHOLD;
+    return { correlation, n, isInverted, isDead };
+}