@jungjaehoon/mama-core 4.1.1 → 5.1.0

package/dist/memory/api.js

@@ -14,12 +14,10 @@ exports.saveMemory = saveMemory;
 exports.saveJudgmentRecord = saveJudgmentRecord;
 exports.boundReadScopesFor = boundReadScopesFor;
 exports.saveLegacyMemory = saveLegacyMemory;
-exports.promoteMemoryStatus = promoteMemoryStatus;
 exports.retireMemoryRecord = retireMemoryRecord;
 exports.buildProfile = buildProfile;
 exports.recallMemory = recallMemory;
 exports.ingestMemory = ingestMemory;
-exports.evolveMemory = evolveMemory;
 exports.buildMemoryBootstrap = buildMemoryBootstrap;
 exports.createAuditAck = createAuditAck;
 exports.recordMemoryAudit = recordMemoryAudit;
@@ -39,6 +37,7 @@ const write_adapters_js_1 = require("./write-adapters.js");
 const decision_formatter_js_1 = require("../decision-formatter.js");
 const debug_logger_js_1 = require("../debug-logger.js");
 const graph_query_js_1 = require("../knowledge/graph-query.js");
+const decision_links_js_1 = require("./decision-links.js");
 const case_search_rollup_js_1 = require("../knowledge/case-search-rollup.js");
 const ranker_rescore_js_1 = require("../knowledge/ranker-rescore.js");
 const ranker_features_js_1 = require("../knowledge/ranker-features.js");
@@ -48,7 +47,6 @@ const index_js_1 = require("../knowledge/index.js");
 const write_adapters_js_2 = require("./write-adapters.js");
 const profile_builder_js_1 = require("./profile-builder.js");
 const bootstrap_builder_js_1 = require("./bootstrap-builder.js");
-const evolution_engine_js_1 = require("./evolution-engine.js");
 const channel_summary_state_store_js_1 = require("./channel-summary-state-store.js");
 const debug_logger_js_2 = require("../debug-logger.js");
 const secret_filter_js_1 = require("./secret-filter.js");
@@ -200,6 +198,24 @@ async function readMemoryRecordById(adapter, memoryId, scopes) {
     const recordScopes = batchLoadScopes(adapter, [id]).get(id) ?? [];
     return toMemoryRecord(row, recordScopes, { package: 'mama-core', source_type: 'db' });
 }
+/** The records that state these corrections, down their chains. */
+function correctionAuthors(corrections) {
+    return corrections.flatMap((correction) => [
+        correction.from,
+        ...correctionAuthors(correction.correctedBy ?? []),
+    ]);
+}
+/** The corrections a reader may see; a hidden correction takes the corrections of it along. */
+function readableCorrections(corrections, readable) {
+    const kept = corrections.filter(readable).map((correction) => {
+        const further = correction.correctedBy
+            ? readableCorrections(correction.correctedBy, readable)
+            : undefined;
+        const { correctedBy: _drop, ...rest } = correction;
+        return further ? { ...rest, correctedBy: further } : rest;
+    });
+    return kept.length > 0 ? kept : undefined;
+}
 function batchLoadScopes(adapter, memoryIds) {
     const scopeMap = new Map();
     if (memoryIds.length === 0)
@@ -467,7 +483,7 @@ async function loadEdgesForIds(adapter, ids) {
     const placeholders = ids.map(() => '?').join(', ');
     const rows = adapter
         .prepare(`SELECT from_id, to_id, relationship AS type, reason
-       FROM decision_edges
+       FROM ${graph_query_js_1.STATED_DECISION_EDGES} e
        WHERE (from_id IN (${placeholders}) OR to_id IN (${placeholders}))
          AND (approved_by_user != 0 OR approved_by_user IS NULL)`)
         .all(...ids, ...ids);
@@ -514,7 +530,7 @@ function guidancePayloadFor(input) {
     }
     return { guidance };
 }
-async function saveMemoryInternal(adapter, input, provenance, access, trustedEnvelope, legacy, commandIdOverride) {
+async function saveMemoryInternal(adapter, input, provenance, access, legacy, commandIdOverride) {
     const targetStatus = input.status ?? 'active';
     const requestedScopes = input.scopes ?? [];
     const payload = guidancePayloadFor(input);
@@ -528,23 +544,10 @@ async function saveMemoryInternal(adapter, input, provenance, access, trustedEnv
     });
     const commandId = commandIdOverride ?? `save:${buildDecisionId(input.topic)}`;
     const recordId = (0, index_js_1.judgmentRecordId)(commandId);
-    // Relationships are persisted only when the caller names their target ids
-    // explicitly. Matching topic text or vector similarity is evidence for
-    // retrieval, not identity.
-    const explicitRelationships = Array.from(new Map((legacy?.relationships ?? []).flatMap((relationship) => relationship.targetIds.map((targetId) => [
-        `${relationship.type}:${targetId}`,
-        { type: relationship.type, targetId },
-    ]))).values());
-    (0, write_adapters_js_2.assertRelationshipTargetsVisible)(adapter, explicitRelationships.map((relationship) => relationship.targetId), access.scopes, trustedEnvelope);
-    const { links, replaces, decisionEdges, supersedeTargets } = (0, write_adapters_js_2.relationshipsToCommandFields)(explicitRelationships, { trusted: trustedEnvelope });
-    const authoredLinks = [...links, ...(input.links ?? [])];
-    const authoredReplacements = [...replaces, ...(input.replaces ?? [])];
-    const allSupersedeTargets = [
-        ...new Set([
-            ...supersedeTargets,
-            ...(input.replaces ?? []).map((replacement) => replacement.id),
-        ]),
-    ];
+    // A relation is written only when the caller names its target and reason (`links`,
+    // `replaces`); matching topic text or vector similarity is evidence for retrieval, not a link.
+    const authoredLinks = input.links ?? [];
+    const authoredReplacements = input.replaces ?? [];
     const embeddingDecision = {
         id: recordId,
         topic: input.topic,
@@ -591,8 +594,6 @@ async function saveMemoryInternal(adapter, input, provenance, access, trustedEnv
             reason: buildSaveEventReason(provenance.tool_name, provenance.gateway_call_id),
         },
         projections: {
-            decisionEdges,
-            ...(allSupersedeTargets.length > 0 ? { supersedeTargets: allSupersedeTargets } : {}),
             ...(input.itemId !== undefined || input.actors !== undefined
                 ? {
                     recordIdentity: { itemId: input.itemId ?? null, actors: input.actors ?? [] },
@@ -621,8 +622,26 @@ async function saveMemoryInternal(adapter, input, provenance, access, trustedEnv
 async function saveMemory(adapter, input) {
     const clean = (0, provenance_js_1.sanitizePublicSaveMemoryInput)(input);
     const provenance = (0, provenance_js_1.normalizeMemoryWriteProvenance)();
-    const access = (0, write_adapters_js_2.writeAccessForProvenance)(provenance, clean.scopes ?? []);
-    return saveMemoryInternal(adapter, clean, provenance, access, false);
+    const access = (0, write_adapters_js_2.writeAccessForProvenance)(provenance, uniqueScopes([...(clean.scopes ?? []), ...namedTargetScopes(adapter, clean)]));
+    return saveMemoryInternal(adapter, clean, provenance, access);
+}
+/**
+ * The scopes of the records a direct save names in `links` and `replaces`. A direct caller has no
+ * grant of its own, so naming a record admits its partition for that link, as `mama.link` does;
+ * the new record is still bound only to its own scopes.
+ */
+function namedTargetScopes(adapter, input) {
+    const ids = [
+        ...(input.links ?? [])
+            .filter((link) => link.target.kind === 'memory')
+            .map((link) => link.target.id),
+        ...(input.replaces ?? []).map((replacement) => replacement.id),
+    ];
+    return ids.flatMap((id) => (0, write_adapters_js_2.boundScopesOf)(adapter, id));
+}
+/** Access scopes must be unique; the save's own scope and a target's are often the same. */
+function uniqueScopes(scopes) {
+    return [...new Map(scopes.map((scope) => [`${scope.kind}\0${scope.id}`, scope])).values()];
 }
 /**
  * The unified `memory.save` action path. Access IS the call authority — the
@@ -650,7 +669,7 @@ async function saveJudgmentRecord(adapter, input, access, commandId, session) {
         source_message_ref: session?.sourceMessageRef,
         source_refs: session?.sourceRefs ? [...session.sourceRefs] : undefined,
     });
-    return saveMemoryInternal(adapter, clean, provenance, access, true, undefined, commandId);
+    return saveMemoryInternal(adapter, clean, provenance, access, undefined, commandId);
 }
 /**
  * The read-side scope rule for memory actions — the same bound `appendJudgment`
@@ -689,173 +708,12 @@ function boundReadScopesFor(access, requested) {
 async function saveLegacyMemory(adapter, input, legacy, access) {
     const clean = (0, provenance_js_1.sanitizePublicSaveMemoryInput)(input);
     const provenance = (0, provenance_js_1.normalizeMemoryWriteProvenance)();
-    const effectiveAccess = access ?? (0, write_adapters_js_2.writeAccessForProvenance)(provenance, clean.scopes ?? []);
-    return saveMemoryInternal(adapter, clean, provenance, effectiveAccess, access !== undefined, legacy);
-}
-async function promoteMemoryStatus(adapter, input) {
-    const memoryId = input.memoryId;
-    const now = input.nowMs ?? Date.now();
-    const targetStatus = input.status;
-    const row = adapter
-        .prepare(`
-        SELECT id, topic, decision, confidence, kind, summary, supersedes
-        FROM decisions
-        WHERE id = ?
-      `)
-        .get(memoryId);
-    if (!row) {
-        throw new Error(`Cannot promote missing memory ${memoryId}`);
-    }
-    const topic = String(row.topic);
-    const summary = String(row.summary ?? row.decision ?? '');
-    const kind = (row.kind ?? 'fact') || 'fact';
-    const scopes = batchLoadScopes(adapter, [memoryId]).get(memoryId) ?? [];
-    let evolution = { edges: [] };
-    if (targetStatus === 'active') {
-        const primaryScope = scopes[0] ?? null;
-        let existingCandidates;
-        if (primaryScope) {
-            const scopeId = (0, db_manager_js_1.ensureMemoryScope)(adapter, primaryScope.kind, primaryScope.id);
-            existingCandidates = adapter
-                .prepare(`
-            SELECT d.id, d.topic, d.summary, d.kind
-            FROM decisions d
-            JOIN memory_scope_bindings msb ON msb.memory_id = d.id
-            WHERE d.topic = ? AND msb.scope_id = ? AND d.id <> ?
-              AND (d.status = 'active' OR d.status IS NULL)
-              AND d.superseded_by IS NULL
-            ORDER BY d.created_at DESC
-            LIMIT 5
-          `)
-                .all(topic, scopeId, memoryId);
-        }
-        else {
-            existingCandidates = adapter
-                .prepare(`
-            SELECT id, topic, summary, kind
-            FROM decisions
-            WHERE topic = ? AND id <> ?
-              AND (status = 'active' OR status IS NULL)
-              AND superseded_by IS NULL
-            ORDER BY created_at DESC
-            LIMIT 5
-          `)
-                .all(topic, memoryId);
-        }
-        if (existingCandidates.length === 0) {
-            try {
-                const queryText = `${topic} ${summary}`;
-                const embedding = await (0, embedder_js_1.generateEmbedding)(queryText, 'query');
-                // Same exclusion as saveMemoryInternal's fallback: superseded history must
-                // not crowd out the prior ACTIVE decision from the 3 candidate slots.
-                const semanticResults = await (0, search_js_1.vectorSearch)(adapter, embedding, 3, 0.82, undefined, Array.from(EXCLUDED_STATUSES));
-                let scopeFiltered = semanticResults;
-                if (primaryScope) {
-                    const semIds = semanticResults.map((result) => String(result.id));
-                    const semScopeMap = batchLoadScopes(adapter, semIds);
-                    const scopeKey = `${primaryScope.kind}:${primaryScope.id}`;
-                    scopeFiltered = semanticResults.filter((result) => {
-                        const resultScopes = semScopeMap.get(String(result.id)) ?? [];
-                        return (resultScopes.length === 0 ||
-                            resultScopes.some((scope) => `${scope.kind}:${scope.id}` === scopeKey));
-                    });
-                }
-                existingCandidates = scopeFiltered
-                    .filter((result) => String(result.id) !== memoryId)
-                    .filter((result) => {
-                    const status = String(result.status || '');
-                    return !status || status === 'active' || status === '';
-                })
-                    .map((result) => ({
-                    id: String(result.id),
-                    topic: String(result.topic || ''),
-                    summary: String(result.decision || ''),
-                    kind: 'fact',
-                    _semanticMatch: true,
-                }));
-            }
-            catch {
-                // Semantic search unavailable — proceed with exact-match candidates only.
-            }
-        }
-        evolution = (0, evolution_engine_js_1.resolveMemoryEvolution)({
-            incoming: { topic, summary, kind },
-            existing: existingCandidates.map((candidate) => ({
-                ...candidate,
-                kind: (candidate.kind || 'fact'),
-            })),
-        });
-    }
-    const existingSupersedesTarget = typeof row.supersedes === 'string' && row.supersedes.length > 0 ? row.supersedes : null;
-    const supersedesTarget = evolution.edges.find((edge) => edge.type === 'supersedes')?.to_id ??
-        (targetStatus === 'active' ? existingSupersedesTarget : null);
-    // The status change is an authored amendment: one append-only judgment record
-    // carries it, and the target row's projection columns move in the same
-    // transaction. A replayed command (same id, same payload) returns the stored
-    // receipt instead of rewriting.
-    const commandId = `promote:${memoryId}:${node_crypto_1.default
-        .createHash('sha256')
-        .update((0, canonicalize_js_1.canonicalizeJSON)({
-        status: targetStatus,
-        supersedes: supersedesTarget,
-        edges: evolution.edges.map((edge) => `${edge.type}:${edge.to_id}`),
-        now,
-    }))
-        .digest('hex')
-        .slice(0, 16)}`;
-    const supersedesEdges = evolution.edges.filter((edge) => edge.type === 'supersedes');
-    const command = {
-        commandId,
-        // Audit records link to the amended memory instead of sharing its topic,
-        // keeping them out of the topic's evolution candidate pool.
-        topic: `judgment/${memoryId}`,
-        summary: `Status '${targetStatus}' applied to ${memoryId}`,
-        recordKind: 'judgment',
-        payload: {
-            amended: memoryId,
-            status: targetStatus,
-            supersedes: supersedesTarget,
-            edges: evolution.edges.map((edge) => ({ type: edge.type, to_id: edge.to_id })),
-        },
-        scopes,
-        agentId: null,
-        links: [{ relation: 'amends', target: { kind: 'memory', id: memoryId } }],
-        amends: [
-            // supersedes is included only when a target resolved: applyAmendment
-            // writes a column for every key present, so a null here would clear the
-            // target's predecessor pointer on non-active promotions.
-            {
-                target: { kind: 'memory', id: memoryId },
-                status: targetStatus,
-                ...(supersedesTarget !== null ? { supersedes: supersedesTarget } : {}),
-            },
-            ...supersedesEdges.map((edge) => ({
-                target: { kind: 'memory', id: edge.to_id },
-                supersededBy: memoryId,
-                status: 'superseded',
-            })),
-        ],
-        projections: {
-            decisionEdges: evolution.edges.map((edge) => ({
-                fromId: memoryId,
-                targetId: edge.to_id,
-                relationship: edge.type,
-                reason: edge.reason ?? null,
-                weight: 1,
-            })),
-        },
-        record: {
-            kind: 'fact',
-            status: 'active',
-            summary: `Status '${targetStatus}' applied to ${memoryId}`,
-        },
-        recordedAt: now,
-        event: { reason: `promote ${memoryId} to '${targetStatus}'` },
-    };
-    await (0, index_js_1.appendJudgment)(command, (0, write_adapters_js_2.unsignedWriteAccess)(scopes), { adapter });
+    const effectiveAccess = access ??
+        (0, write_adapters_js_2.writeAccessForProvenance)(provenance, uniqueScopes([...(clean.scopes ?? []), ...namedTargetScopes(adapter, clean)]));
+    return saveMemoryInternal(adapter, clean, provenance, effectiveAccess, legacy);
 }
 /** Append an access-checked status amendment for one stored memory record. */
-async function retireMemoryRecord(adapter, input, access, commandId) {
+async function retireMemoryRecord(adapter, input, access, commandId, session) {
     const id = input.memoryId.trim();
     const reason = input.reason.trim();
     if (!id)
@@ -871,11 +729,30 @@ async function retireMemoryRecord(adapter, input, access, commandId) {
     }
     const admittedScopes = record.scopes.filter((recordScope) => access.scopes.some((scope) => scope.kind === recordScope.kind && scope.id === recordScope.id));
     const summary = `Status '${input.status}' applied to ${id}: ${reason}`;
+    // Who retired it, stated by the host as for a save, so a retirement can be traced to its turn.
+    const provenance = (0, provenance_js_1.normalizeMemoryWriteProvenance)({
+        actor: session?.actor ?? 'main_agent',
+        agent_id: access.agentId,
+        model_run_id: session?.modelRunId,
+        envelope_hash: session?.envelopeHash,
+        tool_name: session?.toolName,
+        gateway_call_id: session?.gatewayCallId,
+        context_packet_id: session?.contextPacketId,
+        source_turn_id: session?.sourceTurnId,
+        source_message_ref: session?.sourceMessageRef,
+        source_refs: session?.sourceRefs ? [...session.sourceRefs] : undefined,
+    });
     const receipt = await (0, index_js_1.appendJudgment)({
         commandId,
         topic: `judgment/${id}`,
         summary,
         recordKind: 'judgment',
+        sourceRefs: provenance.source_refs,
+        provenance: provenance.provenance,
+        agentId: provenance.agent_id,
+        modelRunId: provenance.model_run_id,
+        envelopeHash: provenance.envelope_hash,
+        gatewayCallId: provenance.gateway_call_id,
         payload: { amended: id, status: input.status, reason },
         scopes: admittedScopes,
         links: [{ relation: 'amends', target: { kind: 'memory', id } }],
@@ -889,12 +766,15 @@ async function buildProfile(adapter, scopes) {
     const records = await loadScopedMemories(adapter, scopes);
     return (0, profile_builder_js_1.classifyProfileEntries)(records);
 }
-const EXCLUDED_STATUSES = new Set([
-    'superseded',
-    'quarantined',
-    'contradicted',
-    'stale',
-]);
+const EXCLUDED_STATUSES = new Set(search_js_1.RECALL_EXCLUDED_STATUSES);
+/** The ids among these that only amend another record (a retirement or an outcome change). */
+function amendmentIds(adapter, ids) {
+    const rows = adapter
+        .prepare(`SELECT id FROM decisions WHERE id IN (${ids.map(() => '?').join(',')})
+         AND json_extract(payload_json, '$.amended') IS NOT NULL`)
+        .all(...ids);
+    return new Set(rows.map((row) => row.id));
+}
 async function recallMemory(adapter, query, options = {}) {
     const bundle = (0, types_js_1.createEmptyRecallBundle)(query);
     const searchOptions = (0, search_quality_js_1.normalizeSearchQualityOptions)(options);
@@ -1072,7 +952,7 @@ async function recallMemory(adapter, query, options = {}) {
                 .map((t) => stemToken(t))
                 .filter((t) => !FTS5_NOISE_WORDS.has(t));
             const ftsQuery = ftsTokens.length > 0 ? ftsTokens.join(' OR ') : query;
-            const ftsResults = await (0, search_js_1.fts5Search)(searchAdapter, ftsQuery, lexicalLimit, options.kind);
+            const ftsResults = await (0, search_js_1.fts5Search)(searchAdapter, ftsQuery, lexicalLimit, options.kind, options.includeHistory ? undefined : { statuses: [...EXCLUDED_STATUSES], amendments: true });
             if (ftsResults.length > 0) {
                 const adapter = searchAdapter;
                 const fallbackSource = {
@@ -1154,6 +1034,10 @@ async function recallMemory(adapter, query, options = {}) {
             if (options.kind !== undefined) {
                 lexicalRecords = lexicalRecords.filter((r) => matchesKind(r.kind));
             }
+            if (!options.includeHistory && lexicalRecords.length > 0) {
+                const amendments = amendmentIds(adapter, lexicalRecords.map((r) => r.id));
+                lexicalRecords = lexicalRecords.filter((r) => !amendments.has(r.id));
+            }
             lexicalCandidates = buildLexicalCandidates(lexicalRecords, query);
             if (subQueries.length > 1) {
                 for (const sq of subQueries.slice(1)) {
@@ -1329,6 +1213,15 @@ async function recallMemory(adapter, query, options = {}) {
         ];
     });
     fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || acceptedPrimaryIds.has(hit.source_id));
+    // A retirement or an outcome change audits another record; it is not a belief. Default recall
+    // leaves it out and history shows it. Only the host writers put `amended` in a payload.
+    if (!options.includeHistory && matched.length > 0) {
+        const amendments = amendmentIds(adapter, matched.map((record) => record.id));
+        if (amendments.size > 0) {
+            matched = matched.filter((record) => !amendments.has(record.id));
+            fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || !amendments.has(hit.source_id));
+        }
+    }
     // Honor options.limit on the final memories (matched is RRF-rank-sorted, canonical
     // dual-write appends last). Without this cap the full fusion set (hundreds of records)
     // flowed into bundle.memories AND the per-record enrichment SQL loops below.
@@ -1340,14 +1233,20 @@ async function recallMemory(adapter, query, options = {}) {
         const cappedIds = new Set(matched.map((record) => record.id));
         fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || cappedIds.has(hit.source_id));
     }
-    // Enrich active records with summaries from their superseded predecessors.
-    // When ingestConversation extracts multiple facts under the same topic, only
-    // the last survives as "active" — the earlier ones become superseded and are
-    // excluded from search.  This recovers their key information so it is not lost.
+    // Superseded records are excluded from search, so an active record carries what it replaced:
+    // the reader sees the correction and what it corrected. A predecessor is shown only inside the
+    // reader's scopes, and marked as replaced.
     if (matched.length > 0) {
         const stmtChain = adapter.prepare(`SELECT id, summary, decision FROM decisions WHERE superseded_by = ?`);
+        const readerScopes = options.scopes && options.scopes.length > 0
+            ? new Set(options.scopes.map((scope) => `${scope.kind}:${scope.id}`))
+            : null;
         for (const record of matched) {
-            const predecessors = stmtChain.all(record.id);
+            let predecessors = stmtChain.all(record.id);
+            if (readerScopes && predecessors.length > 0) {
+                const scopeMap = batchLoadScopes(adapter, predecessors.map((predecessor) => predecessor.id));
+                predecessors = predecessors.filter((predecessor) => (scopeMap.get(predecessor.id) ?? []).some((scope) => readerScopes.has(`${scope.kind}:${scope.id}`)));
+            }
             if (predecessors.length > 0) {
                 const extra = predecessors
                     .map((p) => String(p.summary ?? p.decision ?? ''))
@@ -1355,8 +1254,8 @@ async function recallMemory(adapter, query, options = {}) {
                     .join(' | ');
                 if (extra) {
                     record.details = record.details
-                        ? `${record.details}\n[Prior context] ${extra}`
-                        : `[Prior context] ${extra}`;
+                        ? `${record.details}\n[Replaced by this record] ${extra}`
+                        : `[Replaced by this record] ${extra}`;
                 }
             }
         }
@@ -1366,124 +1265,138 @@ async function recallMemory(adapter, query, options = {}) {
     bundle.graph_context.expanded = [];
     bundle.graph_context.edges = [];
     if (matched.length > 0 && !options.skipGraphExpansion && searchOptions.includeRelated) {
-        try {
-            const candidates = matched.map((m) => ({
-                id: m.id,
-                topic: m.topic,
-                decision: m.summary,
-                confidence: m.confidence,
-                created_at: m.created_at,
-                similarity: m.confidence ?? 0.5,
-            }));
-            const expanded = await expandWithGraphInAdapter(adapter, candidates);
-            const primaryIds = new Set(matched.map((m) => m.id));
-            let expandedOnly = expanded.filter((e) => !primaryIds.has(e.id));
-            let expandedScopeMap = new Map();
-            // Re-filter expanded results: apply status and scope checks
-            if (!options.includeHistory) {
-                expandedOnly = expandedOnly.filter((e) => {
-                    const row = adapter
-                        .prepare(`SELECT kind, status FROM decisions WHERE id = ?`)
-                        .get(e.id);
-                    const status = row?.status || '';
-                    return matchesKind(row?.kind) && (!status || !EXCLUDED_STATUSES.has(status));
-                });
-            }
-            else if (options.kind !== undefined) {
-                expandedOnly = expandedOnly.filter((e) => {
-                    const row = adapter.prepare(`SELECT kind FROM decisions WHERE id = ?`).get(e.id);
-                    return matchesKind(row?.kind);
-                });
-            }
-            if (options.scopes && options.scopes.length > 0) {
-                const expandedIds = expandedOnly.map((e) => e.id);
-                expandedScopeMap = batchLoadScopes(adapter, expandedIds);
-                const requestedScopes = new Set(options.scopes.map((s) => `${s.kind}:${s.id}`));
-                expandedOnly = expandedOnly.filter((e) => {
-                    const scopes = expandedScopeMap.get(e.id) ?? [];
-                    if (scopes.length === 0)
-                        return false;
-                    return scopes.some((s) => requestedScopes.has(`${s.kind}:${s.id}`));
-                });
-            }
-            bundle.graph_context.expanded = expandedOnly.flatMap((e) => {
-                const kindRow = adapter.prepare(`SELECT kind FROM decisions WHERE id = ?`).get(e.id);
-                const expandedRecord = {
-                    id: String(e.id),
-                    topic: String(e.topic || ''),
-                    kind: (kindRow?.kind ?? 'decision'),
-                    summary: String(e.decision || ''),
-                    details: '',
-                    confidence: e.graph_rank ?? 0.5,
-                    status: 'active',
-                    scopes: expandedScopeMap.get(e.id) ?? [],
-                    source: {
-                        package: 'mama-core',
-                        source_type: String(e.graph_source || 'graph_expansion'),
-                    },
-                    created_at: e.created_at ?? Date.now(),
-                    updated_at: e.created_at ?? Date.now(),
-                };
-                const expandedDiagnostics = buildDiagnostics(expandedRecord, 'expanded');
-                if (!passesStrictness(expandedDiagnostics)) {
-                    diagnostics.candidate_counts.rejected_by_strictness += 1;
-                    return [];
-                }
-                return [
-                    searchOptions.diagnostics
-                        ? {
-                            ...expandedRecord,
-                            retrieval_diagnostics: expandedDiagnostics,
-                        }
-                        : expandedRecord,
-                ];
+        const candidates = matched.map((m) => ({
+            id: m.id,
+            topic: m.topic,
+            decision: m.summary,
+            confidence: m.confidence,
+            created_at: m.created_at,
+            similarity: m.confidence ?? 0.5,
+        }));
+        const expanded = await expandWithGraphInAdapter(adapter, candidates);
+        const primaryIds = new Set(matched.map((m) => m.id));
+        let expandedOnly = expanded.filter((e) => !primaryIds.has(e.id));
+        let expandedScopeMap = new Map();
+        // Re-filter expanded results: apply status and scope checks
+        if (!options.includeHistory) {
+            expandedOnly = expandedOnly.filter((e) => {
+                const row = adapter.prepare(`SELECT kind, status FROM decisions WHERE id = ?`).get(e.id);
+                const status = row?.status || '';
+                return matchesKind(row?.kind) && (!status || !EXCLUDED_STATUSES.has(status));
             });
-            diagnostics.candidate_counts.graph_expanded = bundle.graph_context.expanded.length;
-            // Graph-expanded hits are supporting context for the primary matches -
-            // they must never OUTRANK them. The previous score ((graph_rank)*0.1,
-            // typically 0.05-0.095) sat far above the entire RRF range (<=~0.018),
-            // so expansion hits displaced every primary hit from the fused top-N
-            // (delta-bench root cause: top-5 filled with related-but-wrong topics
-            // while the queried topic's own rows were cut). Scale them into a band
-            // strictly below the weakest primary hit, ordered by graph rank.
-            const minPrimaryScore = fusedHits.length > 0 ? Math.min(...fusedHits.map((hit) => hit.fused_rank_score)) : 0.002;
-            fusedHits = [
-                ...fusedHits,
-                ...bundle.graph_context.expanded.map((record) => ({
-                    source_type: 'decision',
-                    source_id: record.id,
-                    record,
-                    fused_rank_score: minPrimaryScore * 0.9 * Math.min(1, Math.max(0.1, record.confidence ?? 0.5)),
-                    retrieval_diagnostics: record.retrieval_diagnostics,
-                })),
-            ].sort((left, right) => right.fused_rank_score - left.fused_rank_score);
-            // bundle.graph_context.expanded is the strictness-filtered set of
-            // expanded nodes that will actually be returned. Use those IDs (not
-            // expandedOnly, which still contains rejected candidates) so edges
-            // never point at nodes that never made it into the graph payload.
-            const acceptedExpandedIds = bundle.graph_context.expanded.map((record) => record.id);
-            const allIds = [...matched.map((m) => m.id), ...acceptedExpandedIds];
-            const allEdges = await loadEdgesForIds(adapter, allIds);
-            // Filter out edges pointing to decisions with excluded statuses
-            const activeIds = new Set(allIds);
-            const edgesToCheck = allEdges.filter((e) => !activeIds.has(e.to_id) || !activeIds.has(e.from_id));
-            if (edgesToCheck.length > 0) {
-                const checkIds = [
-                    ...new Set(edgesToCheck.flatMap((e) => [e.from_id, e.to_id]).filter((id) => !activeIds.has(id))),
-                ];
-                const placeholders = checkIds.map(() => '?').join(', ');
-                const statusRows = adapter
-                    .prepare(`SELECT id, status FROM decisions WHERE id IN (${placeholders})`)
-                    .all(...checkIds);
-                const excludedIds = new Set(statusRows.filter((r) => r.status && EXCLUDED_STATUSES.has(r.status)).map((r) => r.id));
-                bundle.graph_context.edges = allEdges.filter((e) => !excludedIds.has(e.from_id) && !excludedIds.has(e.to_id));
+            // A link an agent stated can point at a retirement or an outcome change; it stays out too.
+            if (expandedOnly.length > 0) {
+                const amendments = amendmentIds(adapter, expandedOnly.map((e) => e.id));
+                expandedOnly = expandedOnly.filter((e) => !amendments.has(e.id));
             }
-            else {
-                bundle.graph_context.edges = allEdges;
+        }
+        else if (options.kind !== undefined) {
+            expandedOnly = expandedOnly.filter((e) => {
+                const row = adapter.prepare(`SELECT kind FROM decisions WHERE id = ?`).get(e.id);
+                return matchesKind(row?.kind);
+            });
+        }
+        if (options.scopes && options.scopes.length > 0) {
+            const expandedIds = expandedOnly.map((e) => e.id);
+            expandedScopeMap = batchLoadScopes(adapter, expandedIds);
+            const requestedScopes = new Set(options.scopes.map((s) => `${s.kind}:${s.id}`));
+            expandedOnly = expandedOnly.filter((e) => {
+                const scopes = expandedScopeMap.get(e.id) ?? [];
+                if (scopes.length === 0)
+                    return false;
+                return scopes.some((s) => requestedScopes.has(`${s.kind}:${s.id}`));
+            });
+            // A correction is stated by a record; its reason shows under the rule the records follow.
+            const correctionScopes = batchLoadScopes(adapter, expandedOnly.flatMap((e) => correctionAuthors(e.edge_corrected_by ?? [])));
+            const readable = (correction) => (correctionScopes.get(correction.from) ?? []).some((scope) => requestedScopes.has(`${scope.kind}:${scope.id}`));
+            expandedOnly = expandedOnly.map((e) => e.edge_corrected_by
+                ? { ...e, edge_corrected_by: readableCorrections(e.edge_corrected_by, readable) }
+                : e);
+        }
+        bundle.graph_context.expanded = expandedOnly.flatMap((e) => {
+            const kindRow = adapter.prepare(`SELECT kind FROM decisions WHERE id = ?`).get(e.id);
+            const expandedRecord = {
+                id: String(e.id),
+                topic: String(e.topic || ''),
+                kind: (kindRow?.kind ?? 'decision'),
+                summary: String(e.decision || ''),
+                details: '',
+                confidence: e.graph_rank ?? 0.5,
+                status: 'active',
+                scopes: expandedScopeMap.get(e.id) ?? [],
+                source: {
+                    package: 'mama-core',
+                    source_type: String(e.graph_source || 'graph_expansion'),
+                },
+                created_at: e.created_at ?? Date.now(),
+                updated_at: e.created_at ?? Date.now(),
+                ...(e.related_to
+                    ? {
+                        reached_through: {
+                            from: e.related_to,
+                            relation: String(e.graph_source),
+                            reason: e.edge_reason ?? null,
+                            ...(e.edge_corrected_by ? { corrected_by: e.edge_corrected_by } : {}),
+                        },
+                    }
+                    : {}),
+            };
+            const expandedDiagnostics = buildDiagnostics(expandedRecord, 'expanded');
+            if (!passesStrictness(expandedDiagnostics)) {
+                diagnostics.candidate_counts.rejected_by_strictness += 1;
+                return [];
             }
+            return [
+                searchOptions.diagnostics
+                    ? {
+                        ...expandedRecord,
+                        retrieval_diagnostics: expandedDiagnostics,
+                    }
+                    : expandedRecord,
+            ];
+        });
+        diagnostics.candidate_counts.graph_expanded = bundle.graph_context.expanded.length;
+        // Graph-expanded hits are supporting context for the primary matches -
+        // they must never OUTRANK them. The previous score ((graph_rank)*0.1,
+        // typically 0.05-0.095) sat far above the entire RRF range (<=~0.018),
+        // so expansion hits displaced every primary hit from the fused top-N
+        // (delta-bench root cause: top-5 filled with related-but-wrong topics
+        // while the queried topic's own rows were cut). Scale them into a band
+        // strictly below the weakest primary hit, ordered by graph rank.
+        const minPrimaryScore = fusedHits.length > 0 ? Math.min(...fusedHits.map((hit) => hit.fused_rank_score)) : 0.002;
+        fusedHits = [
+            ...fusedHits,
+            ...bundle.graph_context.expanded.map((record) => ({
+                source_type: 'decision',
+                source_id: record.id,
+                record,
+                fused_rank_score: minPrimaryScore * 0.9 * Math.min(1, Math.max(0.1, record.confidence ?? 0.5)),
+                retrieval_diagnostics: record.retrieval_diagnostics,
+            })),
+        ].sort((left, right) => right.fused_rank_score - left.fused_rank_score);
+        // bundle.graph_context.expanded is the strictness-filtered set of
+        // expanded nodes that will actually be returned. Use those IDs (not
+        // expandedOnly, which still contains rejected candidates) so edges
+        // never point at nodes that never made it into the graph payload.
+        const acceptedExpandedIds = bundle.graph_context.expanded.map((record) => record.id);
+        const allIds = [...matched.map((m) => m.id), ...acceptedExpandedIds];
+        const allEdges = await loadEdgesForIds(adapter, allIds);
+        // Filter out edges pointing to decisions with excluded statuses
+        const activeIds = new Set(allIds);
+        const edgesToCheck = allEdges.filter((e) => !activeIds.has(e.to_id) || !activeIds.has(e.from_id));
+        if (edgesToCheck.length > 0) {
+            const checkIds = [
+                ...new Set(edgesToCheck.flatMap((e) => [e.from_id, e.to_id]).filter((id) => !activeIds.has(id))),
+            ];
+            const placeholders = checkIds.map(() => '?').join(', ');
+            const statusRows = adapter
+                .prepare(`SELECT id, status FROM decisions WHERE id IN (${placeholders})`)
+                .all(...checkIds);
+            const excludedIds = new Set(statusRows.filter((r) => r.status && EXCLUDED_STATUSES.has(r.status)).map((r) => r.id));
+            bundle.graph_context.edges = allEdges.filter((e) => !excludedIds.has(e.from_id) && !excludedIds.has(e.to_id));
         }
-        catch {
-            // Graph expansion is best-effort; do not fail recall
+        else {
+            bundle.graph_context.edges = allEdges;
         }
     }
     bundle.fused_hits = fusedHits;
@@ -1546,9 +1459,6 @@ async function ingestMemoryInternal(adapter, input) {
 async function ingestMemory(adapter, input) {
     return ingestMemoryInternal(adapter, (0, provenance_js_1.sanitizePublicIngestMemoryInput)(input));
 }
-async function evolveMemory(input) {
-    return (0, evolution_engine_js_1.resolveMemoryEvolution)(input);
-}
 async function buildMemoryBootstrap(adapter, params) {
     return (0, bootstrap_builder_js_1.buildMemoryAgentBootstrap)(adapter, params);
 }
@@ -1661,6 +1571,7 @@ function confidenceValue(record, fallback) {
 async function expandWithGraphInAdapter(adapter, candidates) {
     const graphEnhanced = new Map(); // Use Map for deduplication by ID
     const primaryIds = new Set(candidates.map((c) => c.id)); // Track primary candidates
+    const reachedThrough = new Map(); // expanded record id -> the link's edge id
     // Process each candidate
     for (const candidate of candidates) {
         // Add primary candidate with higher rank
@@ -1671,97 +1582,96 @@ async function expandWithGraphInAdapter(adapter, candidates) {
                 graph_rank: 1.0, // Highest rank
             });
         }
-        // 1. Add supersedes chain (evolution history)
-        try {
-            const chain = await (0, graph_query_js_1.queryDecisionGraph)(adapter, candidate.topic, candidate.id);
-            for (const decision of chain) {
-                if (!graphEnhanced.has(decision.id)) {
-                    graphEnhanced.set(decision.id, {
-                        ...decision,
-                        graph_source: 'supersedes_chain',
-                        graph_rank: 0.8, // Lower rank than primary
-                        similarity: (candidate.similarity ?? 0) * 0.9, // Inherit similarity, slightly reduced
-                        related_to: candidate.id, // Track relationship
-                    });
-                }
+        // 1. The records this one replaced, down its supersedes chain
+        const chain = await (0, graph_query_js_1.queryDecisionGraph)(adapter, candidate.topic, candidate.id);
+        for (const decision of chain) {
+            if (!graphEnhanced.has(decision.id)) {
+                graphEnhanced.set(decision.id, {
+                    ...decision,
+                    graph_source: 'supersedes_chain',
+                    graph_rank: 0.8, // Lower rank than primary
+                    similarity: (candidate.similarity ?? 0) * 0.9, // Inherit similarity, slightly reduced
+                    related_to: candidate.id, // Track relationship
+                });
             }
         }
-        catch (error) {
-            (0, debug_logger_js_1.warn)(`Failed to get supersedes chain for ${candidate.topic}: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        // 2. Add semantic edges (refines, contradicts, builds_on, debates, synthesizes)
-        try {
-            const rawEdges = (await (0, graph_query_js_1.querySemanticEdges)(adapter, [candidate.id])) || {};
-            const edges = {
-                refines: rawEdges.refines || [],
-                refined_by: rawEdges.refined_by || [],
-                contradicts: rawEdges.contradicts || [],
-                contradicted_by: rawEdges.contradicted_by || [],
-                builds_on: rawEdges.builds_on || [],
-                built_on_by: rawEdges.built_on_by || [],
-                debates: rawEdges.debates || [],
-                debated_by: rawEdges.debated_by || [],
-                synthesizes: rawEdges.synthesizes || [],
-                synthesized_by: rawEdges.synthesized_by || [],
-            };
-            // Helper to add edge to graph
-            const addEdge = (edge, idField, source, rank, simFactor) => {
-                const id = edge[idField];
-                if (!graphEnhanced.has(id)) {
-                    graphEnhanced.set(id, {
-                        id: id,
-                        topic: edge.topic,
-                        decision: edge.decision,
-                        confidence: edge.confidence,
-                        created_at: edge.created_at,
-                        graph_source: source,
-                        graph_rank: rank,
-                        similarity: (candidate.similarity ?? 0) * simFactor,
-                        related_to: candidate.id,
-                        edge_reason: edge.reason,
-                    });
-                }
-            };
-            // Add refines edges
-            for (const edge of edges.refines) {
-                addEdge(edge, 'to_id', 'refines', 0.7, 0.85);
-            }
-            // Add refined_by edges
-            for (const edge of edges.refined_by) {
-                addEdge(edge, 'from_id', 'refined_by', 0.7, 0.85);
-            }
-            // Add contradicts edges (lower rank, but still relevant)
-            for (const edge of edges.contradicts) {
-                addEdge(edge, 'to_id', 'contradicts', 0.6, 0.8);
-            }
-            // Story 2.1: Add builds_on edges (high relevance - extending prior work)
-            for (const edge of edges.builds_on) {
-                addEdge(edge, 'to_id', 'builds_on', 0.75, 0.9);
-            }
-            // Add built_on_by edges (someone built on this decision)
-            for (const edge of edges.built_on_by) {
-                addEdge(edge, 'from_id', 'built_on_by', 0.75, 0.9);
-            }
-            // Add debates edges (alternative view)
-            for (const edge of edges.debates) {
-                addEdge(edge, 'to_id', 'debates', 0.65, 0.85);
-            }
-            // Add debated_by edges
-            for (const edge of edges.debated_by) {
-                addEdge(edge, 'from_id', 'debated_by', 0.65, 0.85);
-            }
-            // Add synthesizes edges (unified approach)
-            for (const edge of edges.synthesizes) {
-                addEdge(edge, 'to_id', 'synthesizes', 0.7, 0.88);
-            }
-            // Add synthesized_by edges
-            for (const edge of edges.synthesized_by) {
-                addEdge(edge, 'from_id', 'synthesized_by', 0.7, 0.88);
+        // 2. The links an agent stated (refines, contradicts, builds_on, debates, synthesizes)
+        const rawEdges = (await (0, graph_query_js_1.querySemanticEdges)(adapter, [candidate.id])) || {};
+        const edges = {
+            refines: rawEdges.refines || [],
+            refined_by: rawEdges.refined_by || [],
+            contradicts: rawEdges.contradicts || [],
+            contradicted_by: rawEdges.contradicted_by || [],
+            builds_on: rawEdges.builds_on || [],
+            built_on_by: rawEdges.built_on_by || [],
+            debates: rawEdges.debates || [],
+            debated_by: rawEdges.debated_by || [],
+            synthesizes: rawEdges.synthesizes || [],
+            synthesized_by: rawEdges.synthesized_by || [],
+        };
+        // Helper to add edge to graph
+        const addEdge = (edge, idField, source, rank, simFactor) => {
+            const id = edge[idField];
+            if (!graphEnhanced.has(id)) {
+                graphEnhanced.set(id, {
+                    id: id,
+                    topic: edge.topic,
+                    decision: edge.decision,
+                    confidence: edge.confidence,
+                    created_at: edge.created_at,
+                    graph_source: source,
+                    graph_rank: rank,
+                    similarity: (candidate.similarity ?? 0) * simFactor,
+                    related_to: candidate.id,
+                    edge_reason: edge.reason,
+                });
+                if (edge.edge_id)
+                    reachedThrough.set(id, edge.edge_id);
             }
+        };
+        // Add refines edges
+        for (const edge of edges.refines) {
+            addEdge(edge, 'to_id', 'refines', 0.7, 0.85);
+        }
+        // Add refined_by edges
+        for (const edge of edges.refined_by) {
+            addEdge(edge, 'from_id', 'refined_by', 0.7, 0.85);
+        }
+        // Add contradicts edges (lower rank, but still relevant)
+        for (const edge of edges.contradicts) {
+            addEdge(edge, 'to_id', 'contradicts', 0.6, 0.8);
+        }
+        // Story 2.1: Add builds_on edges (high relevance - extending prior work)
+        for (const edge of edges.builds_on) {
+            addEdge(edge, 'to_id', 'builds_on', 0.75, 0.9);
         }
-        catch (error) {
-            (0, debug_logger_js_1.warn)(`Failed to get semantic edges for ${candidate.id}: ${error instanceof Error ? error.message : String(error)}`);
+        // Add built_on_by edges (someone built on this decision)
+        for (const edge of edges.built_on_by) {
+            addEdge(edge, 'from_id', 'built_on_by', 0.75, 0.9);
         }
+        // Add debates edges (alternative view)
+        for (const edge of edges.debates) {
+            addEdge(edge, 'to_id', 'debates', 0.65, 0.85);
+        }
+        // Add debated_by edges
+        for (const edge of edges.debated_by) {
+            addEdge(edge, 'from_id', 'debated_by', 0.65, 0.85);
+        }
+        // Add synthesizes edges (unified approach)
+        for (const edge of edges.synthesizes) {
+            addEdge(edge, 'to_id', 'synthesizes', 0.7, 0.88);
+        }
+        // Add synthesized_by edges
+        for (const edge of edges.synthesized_by) {
+            addEdge(edge, 'from_id', 'synthesized_by', 0.7, 0.88);
+        }
+    }
+    // A link the agent later contradicted still leads here; the correction goes with the record.
+    const corrections = (0, decision_links_js_1.correctionsOf)(adapter, [...reachedThrough.values()]);
+    for (const [id, edgeId] of reachedThrough) {
+        const correctedBy = corrections.get(edgeId);
+        if (correctedBy)
+            graphEnhanced.set(id, { ...graphEnhanced.get(id), edge_corrected_by: correctedBy });
     }
     // 3. Convert Map to Array
     const allResults = Array.from(graphEnhanced.values());
@@ -1831,8 +1741,117 @@ function buildRankerMeta(applied, modelId, skippedReason) {
     }
     return meta;
 }
+/** The relations search follows, and their names seen from the other end. */
+const POINTER_RELATIONS = {
+    refines: 'refined_by',
+    contradicts: 'contradicted_by',
+    builds_on: 'built_on_by',
+    debates: 'debated_by',
+    synthesizes: 'synthesized_by',
+    supersedes: 'superseded_by',
+};
+/**
+ * Each direct hit names the records its stated links reach, in both directions, including a link
+ * to another hit. Expanded rows rank below every direct hit (a measured regression when they did
+ * not) and are cut at the usual limits, so the link comes along on its hit instead, and the
+ * reader opens the record it names. A scoped search names only records in its scopes, and a
+ * correction only when the record stating it is in them.
+ */
+function withLinkPointers(rows, adapter, scopes) {
+    const hitIds = rows.filter((row) => !row.related_to).map((row) => row.id);
+    if (hitIds.length === 0)
+        return rows;
+    const hits = hitIds.map(() => '?').join(', ');
+    const relations = Object.keys(POINTER_RELATIONS);
+    const edges = adapter
+        .prepare(`SELECT edge_id, from_id, to_id, relationship, reason FROM ${graph_query_js_1.STATED_DECISION_EDGES} e
+        WHERE (from_id IN (${hits}) OR to_id IN (${hits}))
+          AND relationship IN (${relations.map(() => '?').join(', ')})
+          AND (approved_by_user = 1 OR approved_by_user IS NULL)
+        ORDER BY created_at`)
+        .all(...hitIds, ...hitIds, ...relations);
+    if (edges.length === 0)
+        return rows;
+    const hitSet = new Set(hitIds);
+    const otherIds = [...new Set(edges.flatMap((edge) => [edge.from_id, edge.to_id]))];
+    const records = new Map(adapter
+        .prepare(`SELECT id, topic, decision, status FROM decisions
+            WHERE id IN (${otherIds.map(() => '?').join(', ')})`)
+        .all(...otherIds).map((record) => [record.id, record]));
+    const corrections = (0, decision_links_js_1.correctionsOf)(adapter, edges.flatMap((edge) => (edge.edge_id ? [edge.edge_id] : [])));
+    const requested = scopes?.length ? new Set(scopes.map((s) => `${s.kind}:${s.id}`)) : null;
+    const scopeMap = requested
+        ? batchLoadScopes(adapter, [
+            ...otherIds,
+            ...[...corrections.values()].flatMap((list) => correctionAuthors(list)),
+        ])
+        : new Map();
+    const inScope = (id) => !requested ||
+        (scopeMap.get(id) ?? []).some((scope) => requested.has(`${scope.kind}:${scope.id}`));
+    const byHit = new Map();
+    const point = (hitId, otherId, relation, edge) => {
+        const record = records.get(otherId);
+        if (!record || !inScope(otherId))
+            return;
+        const correctedBy = edge.edge_id ? corrections.get(edge.edge_id) : undefined;
+        const readable = correctedBy
+            ? readableCorrections(correctedBy, (correction) => inScope(correction.from))
+            : undefined;
+        const list = byHit.get(hitId) ?? [];
+        list.push({
+            id: record.id,
+            topic: record.topic,
+            summary: record.decision.split('\n')[0].slice(0, 200),
+            ...(record.status && record.status !== 'active' ? { status: record.status } : {}),
+            relation,
+            reason: edge.reason,
+            ...(readable ? { corrected_by: readable } : {}),
+        });
+        byHit.set(hitId, list);
+    };
+    for (const edge of edges) {
+        if (hitSet.has(edge.from_id))
+            point(edge.from_id, edge.to_id, edge.relationship, edge);
+        if (hitSet.has(edge.to_id))
+            point(edge.to_id, edge.from_id, POINTER_RELATIONS[edge.relationship], edge);
+    }
+    return rows.map((row) => {
+        const links = row.related_to ? undefined : byHit.get(row.id);
+        return links ? { ...row, links } : row;
+    });
+}
+/**
+ * A hit that is one revision of a work item says which one and the item's head. Search ranks an
+ * item's revisions by their text, so an earlier revision can rank above the one that corrected it
+ * (on a copy of the owner's database a revision 16 of 20 ranked first and the head was not in the
+ * top ten); the reader opens the head before answering from an earlier one.
+ */
+function withWorkRevision(rows, adapter) {
+    if (rows.length === 0)
+        return rows;
+    const found = new Map(adapter
+        .prepare(`SELECT a.record_id, a.commitment_id, a.revision, c.current_revision
+             FROM commitment_assignments a
+             JOIN commitments c ON c.commitment_id = a.commitment_id
+            WHERE a.record_id IN (${rows.map(() => '?').join(', ')})`)
+        .all(...rows.map((row) => row.id)).map((row) => [row.record_id, row]));
+    return rows.map((row) => {
+        const work = found.get(row.id);
+        return work
+            ? {
+                ...row,
+                work_item: {
+                    commitment_id: work.commitment_id,
+                    revision: work.revision,
+                    head_revision: work.current_revision,
+                },
+            }
+            : row;
+    });
+}
 function mapRolledUpResult(result) {
     const record = resultRecord(result);
+    const reached = record.reached_through;
     const retrievalDiagnostics = result.retrieval_diagnostics;
     const topic = stringOrNull(record.topic ?? record.title) ?? result.source_id;
     // For wiki_page leaves, prefer the markdown body (`content`) in `decision` so
@@ -1863,10 +1882,13 @@ function mapRolledUpResult(result) {
         created_at: record.created_at ?? null,
         event_date: record.event_date ?? null,
         event_datetime: record.event_datetime ?? null,
-        graph_source: retrievalDiagnostics?.graph_source ?? 'primary',
+        // An expanded record says which hit it came from and through which link, so the reader
+        // can tell it from a direct hit and weigh the link's reason (and any correction of it).
+        graph_source: reached?.relation ?? retrievalDiagnostics?.graph_source ?? 'primary',
         graph_rank: 1,
-        related_to: null,
-        edge_reason: null,
+        related_to: reached?.from ?? null,
+        edge_reason: reached?.reason ?? null,
+        ...(reached?.corrected_by ? { edge_corrected_by: reached.corrected_by } : {}),
         case_id: result.case_id,
         source_type: result.source_type,
         kind: stringOrNull(record.kind) ?? 'decision',
@@ -2026,7 +2048,7 @@ async function suggestInAdapter(adapter, userQuestion, options = {}
         if (rolledUp.length > 0) {
             const filteredResults = rolledUp.slice(0, rerankPoolLimit);
             const { results: mappedResults, meta: rankerMeta } = applyLearnedRanker(filteredResults.map(mapRolledUpResult));
-            const limitedResults = mappedResults.slice(0, limit);
+            const limitedResults = withWorkRevision(withLinkPointers(mappedResults.slice(0, limit), adapter, options.scopes), adapter);
             if (format === 'markdown') {
                 const context = limitedResults
                     .map((result, index) => `${index + 1}. [${result.topic}] ${result.decision}\n   ${result.reasoning}`)
@@ -2091,7 +2113,7 @@ async function suggestInAdapter(adapter, userQuestion, options = {}
                     : {}),
             }));
             const { results: rankedRows, meta: rankerMeta } = applyLearnedRanker(baseRows);
-            const limitedRows = rankedRows.slice(0, limit);
+            const limitedRows = withWorkRevision(withLinkPointers(rankedRows.slice(0, limit), adapter, options.scopes), adapter);
             if (format === 'markdown') {
                 const context = limitedRows
                     .map((row, index) => `${index + 1}. [${row.topic}] ${row.decision}\n   ${row.reasoning}`)