@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/mama-api.js

@@ -22,8 +22,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listRecentMemoryEvents = exports.listOpenAuditFindings = exports.getChannelSummary = exports.upsertChannelSummary = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.saveMemory = void 0;
+exports.listToolTracesForRun = exports.appendToolTrace = exports.getModelRunInAdapter = exports.getModelRun = exports.failModelRunInAdapter = exports.failModelRun = exports.commitModelRunInAdapter = exports.commitModelRun = exports.beginModelRunInAdapter = exports.beginModelRun = exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.listOpenAuditFindings = exports.getChannelSummary = exports.upsertChannelSummary = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestConversationWithTrustedProvenance = exports.ingestConversation = exports.ingestWithTrustedProvenance = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.saveMemoryWithTrustedProvenance = exports.saveMemory = void 0;
 exports.save = save;
+exports.saveWithTrustedProvenance = saveWithTrustedProvenance;
 exports.suggest = suggest;
 exports.list = listDecisions;
 exports.listCheckpoints = listCheckpoints;
@@ -50,6 +51,7 @@ exports.restoreLinkBackup = restoreLinkBackup;
 exports.verifyBackupExists = verifyBackupExists;
 exports.deleteAutoLinks = deleteAutoLinks;
 exports.validateCleanupResult = validateCleanupResult;
+exports.expandWithGraph = expandWithGraph;
 // Node built-ins
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -67,9 +69,13 @@ const ollama_client_js_1 = require("./ollama-client.js");
 const debug_logger_js_1 = require("./debug-logger.js");
 const api_js_1 = require("./memory/api.js");
 Object.defineProperty(exports, "saveMemory", { enumerable: true, get: function () { return api_js_1.saveMemory; } });
+Object.defineProperty(exports, "saveMemoryWithTrustedProvenance", { enumerable: true, get: function () { return api_js_1.saveMemoryWithTrustedProvenance; } });
 Object.defineProperty(exports, "recallMemory", { enumerable: true, get: function () { return api_js_1.recallMemory; } });
 Object.defineProperty(exports, "buildProfile", { enumerable: true, get: function () { return api_js_1.buildProfile; } });
 Object.defineProperty(exports, "ingestMemory", { enumerable: true, get: function () { return api_js_1.ingestMemory; } });
+Object.defineProperty(exports, "ingestWithTrustedProvenance", { enumerable: true, get: function () { return api_js_1.ingestWithTrustedProvenance; } });
+Object.defineProperty(exports, "ingestConversation", { enumerable: true, get: function () { return api_js_1.ingestConversation; } });
+Object.defineProperty(exports, "ingestConversationWithTrustedProvenance", { enumerable: true, get: function () { return api_js_1.ingestConversationWithTrustedProvenance; } });
 Object.defineProperty(exports, "evolveMemory", { enumerable: true, get: function () { return api_js_1.evolveMemory; } });
 Object.defineProperty(exports, "buildMemoryBootstrap", { enumerable: true, get: function () { return api_js_1.buildMemoryBootstrap; } });
 Object.defineProperty(exports, "createAuditAck", { enumerable: true, get: function () { return api_js_1.createAuditAck; } });
@@ -79,7 +85,29 @@ Object.defineProperty(exports, "getChannelSummary", { enumerable: true, get: fun
 const finding_store_js_1 = require("./memory/finding-store.js");
 Object.defineProperty(exports, "listOpenAuditFindings", { enumerable: true, get: function () { return finding_store_js_1.listOpenAuditFindings; } });
 const event_store_js_1 = require("./memory/event-store.js");
+Object.defineProperty(exports, "listMemoryEventsForMemory", { enumerable: true, get: function () { return event_store_js_1.listMemoryEventsForMemory; } });
 Object.defineProperty(exports, "listRecentMemoryEvents", { enumerable: true, get: function () { return event_store_js_1.listRecentMemoryEvents; } });
+const provenance_query_js_1 = require("./memory/provenance-query.js");
+Object.defineProperty(exports, "getMemoryProvenance", { enumerable: true, get: function () { return provenance_query_js_1.getMemoryProvenance; } });
+Object.defineProperty(exports, "listMemoriesByEnvelopeHash", { enumerable: true, get: function () { return provenance_query_js_1.listMemoriesByEnvelopeHash; } });
+Object.defineProperty(exports, "listMemoriesByGatewayCallId", { enumerable: true, get: function () { return provenance_query_js_1.listMemoriesByGatewayCallId; } });
+Object.defineProperty(exports, "listMemoriesByModelRunId", { enumerable: true, get: function () { return provenance_query_js_1.listMemoriesByModelRunId; } });
+const store_js_1 = require("./model-runs/store.js");
+Object.defineProperty(exports, "beginModelRun", { enumerable: true, get: function () { return store_js_1.beginModelRun; } });
+Object.defineProperty(exports, "beginModelRunInAdapter", { enumerable: true, get: function () { return store_js_1.beginModelRunInAdapter; } });
+Object.defineProperty(exports, "commitModelRun", { enumerable: true, get: function () { return store_js_1.commitModelRun; } });
+Object.defineProperty(exports, "commitModelRunInAdapter", { enumerable: true, get: function () { return store_js_1.commitModelRunInAdapter; } });
+Object.defineProperty(exports, "failModelRun", { enumerable: true, get: function () { return store_js_1.failModelRun; } });
+Object.defineProperty(exports, "failModelRunInAdapter", { enumerable: true, get: function () { return store_js_1.failModelRunInAdapter; } });
+Object.defineProperty(exports, "getModelRun", { enumerable: true, get: function () { return store_js_1.getModelRun; } });
+Object.defineProperty(exports, "getModelRunInAdapter", { enumerable: true, get: function () { return store_js_1.getModelRunInAdapter; } });
+const tool_trace_store_js_1 = require("./model-runs/tool-trace-store.js");
+Object.defineProperty(exports, "appendToolTrace", { enumerable: true, get: function () { return tool_trace_store_js_1.appendToolTrace; } });
+Object.defineProperty(exports, "listToolTracesForRun", { enumerable: true, get: function () { return tool_trace_store_js_1.listToolTracesForRun; } });
+const search_rollup_js_1 = require("./cases/search-rollup.js");
+const ranker_rescore_js_1 = require("./search/ranker-rescore.js");
+const ranker_features_js_1 = require("./search/ranker-features.js");
+const search_quality_js_1 = require("./search/search-quality.js");
 // Session-level warning cooldown cache (Story 1.1, 1.2)
 // Prevents spam by tracking warned topics per session
 const warnedTopicsCache = new Map();
@@ -111,7 +139,7 @@ const WARNING_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
  *   outcome: 'success'
  * });
  */
-async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user_decision', outcome = 'pending', failure_reason = null, limitation = null, trust_context: _trust_context = null, is_static, scopes: inputScopes, event_date, }) {
+async function saveInternal({ topic, decision, reasoning, confidence = 0.5, type = 'user_decision', outcome = 'pending', failure_reason = null, limitation = null, trust_context: _trust_context = null, is_static, scopes: inputScopes, event_date, timelineEvent, }, options) {
     // Validate required fields
     if (!topic || typeof topic !== 'string') {
         throw new Error('mama.save() requires topic (string)');
@@ -161,19 +189,35 @@ async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user
     // Future: Will use decision_type column for proper distinction
     const _userInvolvement = type === 'user_decision' ? 'approved' : null;
     (0, progress_indicator_js_1.logProgress)(`Saving decision: ${topic.substring(0, 30)}...`);
-    const { id: decisionId } = await (0, api_js_1.saveMemory)({
-        topic,
-        kind: is_static === 1 ? 'preference' : 'decision',
-        summary: decision,
-        details: reasoning,
-        confidence,
-        scopes: Array.isArray(inputScopes) && inputScopes.length > 0 ? inputScopes : [],
-        source: {
-            package: 'mama-core',
-            source_type: 'legacy_save',
-        },
-        eventDate: event_date ?? undefined,
-    });
+    const { id: decisionId, timeline_event_id: timelineEventId, timeline_event_ids: timelineEventIds, } = options
+        ? await (0, api_js_1.saveMemoryWithTrustedProvenance)({
+            topic,
+            kind: is_static === 1 ? 'preference' : 'decision',
+            summary: decision,
+            details: reasoning,
+            confidence,
+            scopes: Array.isArray(inputScopes) && inputScopes.length > 0 ? inputScopes : [],
+            source: {
+                package: 'mama-core',
+                source_type: 'legacy_save',
+            },
+            eventDate: event_date ?? undefined,
+            timelineEvent,
+        }, options)
+        : await (0, api_js_1.saveMemory)({
+            topic,
+            kind: is_static === 1 ? 'preference' : 'decision',
+            summary: decision,
+            details: reasoning,
+            confidence,
+            scopes: Array.isArray(inputScopes) && inputScopes.length > 0 ? inputScopes : [],
+            source: {
+                package: 'mama-core',
+                source_type: 'legacy_save',
+            },
+            eventDate: event_date ?? undefined,
+            timelineEvent,
+        });
     (0, progress_indicator_js_1.logComplete)(`Decision saved: ${decisionId.substring(0, 20)}...`);
     // Update user_involvement, outcome, failure_reason, limitation
     // Note: learnDecision always sets 'requested', we need to override it
@@ -255,13 +299,17 @@ async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user
                 if (searchResults && typeof searchResults === 'object' && 'results' in searchResults) {
                     // Filter out the decision we just saved
                     similar_decisions = searchResults.results
+                        .filter((d) => d.source_type === 'decision')
                         .filter((d) => d.id !== decisionId)
                         .map((d) => ({
                         id: d.id,
                         topic: d.topic,
                         decision: d.decision,
                         similarity: d.similarity,
+                        retrieval_score: d.retrieval_score ?? null,
                         created_at: d.created_at,
+                        event_date: d.event_date ?? null,
+                        event_datetime: d.event_datetime ?? null,
                     }));
                     if (similar_decisions.length > 0) {
                         (0, progress_indicator_js_1.logComplete)(`Found ${similar_decisions.length} related decision(s)`);
@@ -308,6 +356,9 @@ async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user
     return {
         success: true,
         id: decisionId,
+        saved_decision_id: decisionId,
+        timeline_event_id: timelineEventId ?? null,
+        timeline_event_ids: timelineEventIds ?? [],
         ...(similar_decisions.length > 0 && { similar_decisions }),
         ...(warning && { warning }),
         ...(collaboration_hint && { collaboration_hint }),
@@ -698,62 +749,327 @@ function applyRecencyBoost(results, options = {}) {
     })
         .sort((a, b) => (b.final_score ?? 0) - (a.final_score ?? 0));
 }
+/** Phase 3 Task 33: learned-ranker meta attached to mama.suggest response. */
+function buildRankerMeta(applied, modelId, skippedReason) {
+    const meta = {
+        model_id: modelId,
+        feature_set_version: ranker_features_js_1.SEARCH_RANKER_FEATURE_SET_VERSION,
+        applied,
+        mode: 'offline',
+    };
+    if (skippedReason) {
+        meta.skipped_reason = skippedReason;
+    }
+    return meta;
+}
+function resultRecord(result) {
+    if (typeof result.record === 'object' &&
+        result.record !== null &&
+        !Array.isArray(result.record)) {
+        return result.record;
+    }
+    return {};
+}
+function stringOrNull(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return String(value);
+}
+function numberOrNull(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+    return value;
+}
+function confidenceValue(record, fallback) {
+    const numeric = numberOrNull(record.confidence);
+    if (numeric !== null) {
+        return numeric;
+    }
+    switch (record.confidence) {
+        case 'high':
+            return 0.9;
+        case 'medium':
+            return 0.6;
+        case 'low':
+            return 0.3;
+        default:
+            return fallback;
+    }
+}
+function mapRolledUpResult(result) {
+    const record = resultRecord(result);
+    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
+    // downstream consumers see the meaningful body rather than the short title.
+    // Decision/checkpoint records use their own fields (summary/decision).
+    const isWikiPageLeaf = result.source_type === 'wiki_page';
+    const decision = isWikiPageLeaf
+        ? (stringOrNull(record.content ?? record.summary ?? record.decision ?? record.title) ??
+            result.source_id)
+        : (stringOrNull(record.summary ?? record.decision ?? record.title ?? record.content) ??
+            result.source_id);
+    const reasoning = stringOrNull(record.details ?? record.reasoning ?? record.status_reason ?? record.content) ??
+        '';
+    return {
+        id: result.source_id,
+        topic,
+        decision,
+        reasoning,
+        confidence: confidenceValue(record, result.score),
+        // Back-compat with pre-rollup consumers (swarm-mama-adapter tests,
+        // older callers): similarity mirrors the retrieval score when we don't
+        // have a separate similarity measure. retrieval_score remains the
+        // authoritative field for Phase 3 code paths.
+        similarity: result.score,
+        retrieval_score: result.score,
+        created_at: record.created_at ?? null,
+        event_date: record.event_date ?? null,
+        event_datetime: record.event_datetime ?? null,
+        graph_source: retrievalDiagnostics?.graph_source ?? 'primary',
+        graph_rank: 1,
+        related_to: null,
+        edge_reason: null,
+        case_id: result.case_id,
+        source_type: result.source_type,
+        contributing_leaves: result.contributing_leaves ?? null,
+        ...(result.contributing_leaf_diagnostics
+            ? { contributing_leaf_diagnostics: result.contributing_leaf_diagnostics }
+            : {}),
+        ...(retrievalDiagnostics ? { retrieval_diagnostics: retrievalDiagnostics } : {}),
+    };
+}
+async function save(params) {
+    return saveInternal(params);
+}
+async function saveWithTrustedProvenance(params, options) {
+    return saveInternal(params, options);
+}
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 async function suggest(userQuestion, options = {}) {
     if (!userQuestion || typeof userQuestion !== 'string') {
         throw new Error('mama.suggest() requires userQuestion (string)');
     }
-    const { format = 'json', limit = 5, threshold, useReranking = false, 
+    const { format = 'json', limit = 5, threshold, useReranking = false, rerankWithLearned = false, 
     // Recency boosting parameters (Gaussian Decay - Elasticsearch style)
     recencyWeight = 0.3, // 0-1: How much to weight recency (0.3 = 70% semantic, 30% recency)
     recencyScale = 7, // Days until recency score drops to 50%
     recencyDecay = 0.5, // Score at scale point (0.5 = 50%)
     disableRecency = false, // Set true to disable recency boosting entirely
-     } = options;
+    strict, strictness, includeRelated, minLexicalSupport, diagnostics: includeDiagnostics, } = options;
+    const normalizedSearchOptions = (0, search_quality_js_1.normalizeSearchQualityOptions)({
+        threshold,
+        strict,
+        strictness,
+        disableRecency,
+        includeRelated,
+        topicPrefix: options.topicPrefix,
+        minLexicalSupport,
+        diagnostics: includeDiagnostics,
+    });
+    const memoryV2QualityContractRequested = threshold !== undefined ||
+        strict !== undefined ||
+        strictness !== undefined ||
+        includeRelated !== undefined ||
+        minLexicalSupport !== undefined ||
+        includeDiagnostics === true ||
+        options.topicPrefix !== undefined ||
+        options.scopes !== undefined;
+    const rerankPoolLimit = rerankWithLearned ? Math.max(limit * 4, limit + 5) : limit;
     try {
         const bundle = await (0, api_js_1.recallMemory)(userQuestion, {
             includeProfile: false,
             topicPrefix: options.topicPrefix,
+            limit: rerankPoolLimit,
+            threshold,
+            strict,
+            strictness,
+            disableRecency,
+            includeRelated,
+            minLexicalSupport,
+            diagnostics: includeDiagnostics,
             ...(options.scopes && { scopes: options.scopes }),
         });
+        const diagnosticsByMemoryId = new Map(bundle.memories
+            .filter((memory) => memory.retrieval_diagnostics)
+            .map((memory) => [memory.id, memory.retrieval_diagnostics]));
+        const rawFusedHits = bundle.fused_hits ?? [];
+        const fusedHits = rawFusedHits.map((hit) => {
+            if (hit.source_type !== 'decision') {
+                return hit;
+            }
+            const recordDiagnostics = typeof hit.record === 'object' && hit.record !== null && !Array.isArray(hit.record)
+                ? hit.record.retrieval_diagnostics
+                : undefined;
+            const retrievalDiagnostics = diagnosticsByMemoryId.get(hit.source_id) ?? recordDiagnostics;
+            if (!retrievalDiagnostics) {
+                return hit;
+            }
+            const record = typeof hit.record === 'object' && hit.record !== null && !Array.isArray(hit.record)
+                ? { ...hit.record, retrieval_diagnostics: retrievalDiagnostics }
+                : hit.record;
+            return {
+                ...hit,
+                record,
+                retrieval_diagnostics: retrievalDiagnostics,
+            };
+        });
+        const rolledUp = fusedHits.length > 0 ? (0, search_rollup_js_1.rollUpSearchHits)({ fusedHits, adapter: (0, memory_store_js_1.getAdapter)() }) : [];
+        const diagnosticsResponse = includeDiagnostics === true ? { diagnostics: bundle.search_meta.diagnostics ?? null } : {};
+        // Phase 3 Task 33: compute base ranker meta once so every return path
+        // (rolledUp, memories fallback, vector-search fallback) can attach it.
+        // rerankWithLearned-driven rescoring still only applies to result arrays
+        // that match the ranker's expected shape (id + source_type + case_id).
+        const baseRankerMeta = useReranking
+            ? buildRankerMeta(false, null, 'llm_reranking_requested')
+            : rerankWithLearned
+                ? null // marker: rescoring requested, actual meta set per-path after rescore
+                : buildRankerMeta(false, null, 'feature_disabled');
+        const applyLearnedRanker = (results) => {
+            if (baseRankerMeta !== null) {
+                return { results, meta: baseRankerMeta };
+            }
+            // Phase 3 Task 33: the caller opted in via rerankWithLearned, but the
+            // runtime `search_ranker_enabled` gate still has final say. This lets
+            // operators disable the learned ranker globally during rollback without
+            // touching any caller code.
+            let runtimeEnabled = true;
+            try {
+                runtimeEnabled = (0, ranker_rescore_js_1.isSearchRankerEnabled)((0, memory_store_js_1.getAdapter)());
+            }
+            catch (err) {
+                (0, debug_logger_js_1.warn)(`[mama.suggest] isSearchRankerEnabled check failed: ${String(err)}`);
+            }
+            if (!runtimeEnabled) {
+                return { results, meta: buildRankerMeta(false, null, 'feature_disabled') };
+            }
+            try {
+                const rescored = (0, ranker_rescore_js_1.rescoreSearchResults)((0, memory_store_js_1.getAdapter)(), {
+                    query: userQuestion,
+                    results,
+                });
+                return {
+                    results: rescored.results,
+                    meta: buildRankerMeta(rescored.skipped_reason === undefined, rescored.model_id, rescored.skipped_reason),
+                };
+            }
+            catch (err) {
+                (0, debug_logger_js_1.warn)(`[mama.suggest] learned-ranker rescore failed: ${String(err)}`);
+                return { results, meta: buildRankerMeta(false, null, 'rescore_error') };
+            }
+        };
+        const summarizeGraphExpansion = (rows) => {
+            const sources = {
+                primary: 0,
+                supersedes_chain: 0,
+                refines: 0,
+                refined_by: 0,
+                contradicts: 0,
+            };
+            let expandedCount = 0;
+            for (const row of rows) {
+                const graphSource = row.graph_source ?? 'primary';
+                if (graphSource === 'primary') {
+                    sources.primary += 1;
+                    continue;
+                }
+                expandedCount += 1;
+                if (graphSource in sources) {
+                    const key = graphSource;
+                    sources[key] += 1;
+                }
+            }
+            return {
+                total_results: rows.length,
+                primary_count: sources.primary,
+                expanded_count: expandedCount,
+                sources,
+            };
+        };
+        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);
+            if (format === 'markdown') {
+                const context = limitedResults
+                    .map((result, index) => `${index + 1}. [${result.topic}] ${result.decision}\n   ${result.reasoning}`)
+                    .join('\n');
+                return `🔍 Search method: memory_v2\n${context}`;
+            }
+            return {
+                query: userQuestion,
+                results: limitedResults,
+                ...diagnosticsResponse,
+                meta: {
+                    count: limitedResults.length,
+                    search_method: 'memory_v2',
+                    threshold: normalizedSearchOptions.threshold,
+                    recency_boost: disableRecency
+                        ? null
+                        : {
+                            weight: recencyWeight,
+                            scale: recencyScale,
+                            decay: recencyDecay,
+                        },
+                    graph_expansion: summarizeGraphExpansion(limitedResults),
+                    ranker: rankerMeta,
+                },
+            };
+        }
         if (bundle.memories.length > 0) {
             // recallMemory uses RRF fusion — confidence is overwritten with the normalized
             // retrieval score (0-1 range, where 1.0 = best match in this result set).
             // The original stored confidence is lost after RRF normalization.
             // We capture the retrieval score separately so `similarity` reflects search
             // relevance while `confidence` is passed through as-is from the bundle.
-            let filteredMemories = bundle.memories;
-            // Apply limit
-            filteredMemories = filteredMemories.slice(0, limit);
+            const filteredMemories = bundle.memories.slice(0, rerankPoolLimit);
+            const baseRows = filteredMemories.map((memory) => ({
+                id: memory.id,
+                topic: memory.topic,
+                decision: memory.summary,
+                reasoning: memory.details,
+                confidence: memory.confidence,
+                // recallMemory currently normalizes fused retrieval rank into `confidence`.
+                // Keep that value visible as retrieval_score, but do not pretend it is
+                // semantic similarity; save-time warning logic keys off `similarity`.
+                similarity: null,
+                retrieval_score: memory.confidence ?? null,
+                final_score: memory.confidence ?? null,
+                created_at: memory.created_at,
+                event_date: memory.event_date ?? null,
+                event_datetime: memory.event_datetime ?? null,
+                graph_source: memory.retrieval_diagnostics?.graph_source ?? 'primary',
+                graph_rank: 1,
+                related_to: null,
+                edge_reason: null,
+                case_id: null,
+                source_type: memory.kind ??
+                    memory.source?.source_type ??
+                    memory.source_type ??
+                    memory.type ??
+                    'decision',
+                ...(memory.retrieval_diagnostics
+                    ? { retrieval_diagnostics: memory.retrieval_diagnostics }
+                    : {}),
+            }));
+            const { results: rankedRows, meta: rankerMeta } = applyLearnedRanker(baseRows);
+            const limitedRows = rankedRows.slice(0, limit);
             if (format === 'markdown') {
-                const context = filteredMemories
-                    .map((memory, index) => `${index + 1}. [${memory.topic}] ${memory.summary}\n   ${memory.details}`)
+                const context = limitedRows
+                    .map((row, index) => `${index + 1}. [${row.topic}] ${row.decision}\n   ${row.reasoning}`)
                     .join('\n');
                 return `🔍 Search method: memory_v2\n${context}`;
             }
             return {
                 query: userQuestion,
-                results: filteredMemories.map((memory, idx) => ({
-                    id: memory.id,
-                    topic: memory.topic,
-                    decision: memory.summary,
-                    reasoning: memory.details,
-                    confidence: memory.confidence,
-                    // memory.confidence is the normalized RRF retrieval score (0-1) after
-                    // recallMemory.  Use it as similarity so the field reflects search relevance
-                    // rather than the original stored trust score.
-                    similarity: memory.confidence ?? 1 - idx * 0.01,
-                    created_at: memory.created_at,
-                    event_date: memory.event_date ?? null,
-                    graph_source: 'primary',
-                    graph_rank: 1,
-                    related_to: null,
-                    edge_reason: null,
-                })),
+                results: limitedRows,
+                ...diagnosticsResponse,
                 meta: {
-                    count: filteredMemories.length,
+                    count: limitedRows.length,
                     search_method: 'memory_v2',
-                    threshold: threshold || 'adaptive',
+                    threshold: normalizedSearchOptions.threshold,
                     recency_boost: disableRecency
                         ? null
                         : {
@@ -761,18 +1077,34 @@ async function suggest(userQuestion, options = {}) {
                             scale: recencyScale,
                             decay: recencyDecay,
                         },
-                    graph_expansion: {
-                        total_results: filteredMemories.length,
-                        primary_count: bundle.graph_context.primary.length,
-                        expanded_count: bundle.graph_context.expanded.length,
-                        sources: {
-                            primary: bundle.graph_context.primary.length,
-                            supersedes_chain: 0,
-                            refines: 0,
-                            refined_by: 0,
-                            contradicts: 0,
+                    graph_expansion: summarizeGraphExpansion(limitedRows),
+                    ranker: rankerMeta,
+                },
+            };
+        }
+        if (memoryV2QualityContractRequested) {
+            const emptyRows = [];
+            const { meta: rankerMeta } = applyLearnedRanker(emptyRows);
+            if (format === 'markdown') {
+                return '🔍 Search method: memory_v2\n';
+            }
+            return {
+                query: userQuestion,
+                results: emptyRows,
+                ...diagnosticsResponse,
+                meta: {
+                    count: 0,
+                    search_method: 'memory_v2',
+                    threshold: normalizedSearchOptions.threshold,
+                    recency_boost: disableRecency
+                        ? null
+                        : {
+                            weight: recencyWeight,
+                            scale: recencyScale,
+                            decay: recencyDecay,
                         },
-                    },
+                    graph_expansion: summarizeGraphExpansion(emptyRows),
+                    ranker: rankerMeta,
                 },
             };
         }
@@ -791,7 +1123,7 @@ async function suggest(userQuestion, options = {}) {
             const wordCount = userQuestion.split(/\s+/).length;
             const adaptiveThreshold = threshold !== undefined ? threshold : wordCount < 3 ? 0.7 : 0.6;
             // Vector search
-            results = await (0, memory_store_js_1.vectorSearch)(queryEmbedding, limit * 2, 0.5); // Get more candidates
+            results = await (0, memory_store_js_1.vectorSearch)(queryEmbedding, rerankPoolLimit * 2, 0.5); // Get more candidates
             // Filter by adaptive threshold
             results = results.filter((r) => r.similarity >= adaptiveThreshold);
             // Stage 1.4: Temporal boost — detect time-related queries and boost matching results
@@ -839,7 +1171,7 @@ async function suggest(userQuestion, options = {}) {
             // Stage 1.7: FTS5 hybrid merge (Haiku Memory Layer)
             {
                 try {
-                    const ftsResults = await (0, db_manager_js_1.fts5Search)(userQuestion, limit * 2);
+                    const ftsResults = await (0, db_manager_js_1.fts5Search)(userQuestion, rerankPoolLimit * 2);
                     if (ftsResults.length > 0) {
                         // Normalize FTS5 ranks (BM25 returns negative values, closer to 0 = better)
                         const maxRank = Math.max(...ftsResults.map((r) => Math.abs(r.rank)));
@@ -924,7 +1256,7 @@ async function suggest(userQuestion, options = {}) {
         ORDER BY created_at DESC
         LIMIT ?
       `);
-            const rows = (await stmt.all(...likeParams, limit));
+            const rows = (await stmt.all(...likeParams, rerankPoolLimit));
             results = rows.map((row) => ({
                 ...row,
                 similarity: 0.75, // Assign moderate similarity for keyword matches
@@ -949,8 +1281,32 @@ async function suggest(userQuestion, options = {}) {
         if (useReranking) {
             results = await rerankWithLLM(userQuestion, results);
         }
-        // Slice to limit
-        const finalResults = results.slice(0, limit);
+        const rerankCandidateResults = results.slice(0, rerankPoolLimit);
+        const vectorRows = rerankCandidateResults.map((r) => ({
+            id: r.id,
+            topic: r.topic,
+            decision: r.decision,
+            reasoning: r.reasoning,
+            confidence: r.confidence,
+            similarity: r.similarity,
+            created_at: r.created_at,
+            event_date: r.event_date ?? null,
+            event_datetime: r.event_datetime ?? null,
+            // Recency metadata (NEW - Gaussian Decay)
+            recency_score: r.recency_score,
+            recency_age_days: r.recency_age_days,
+            final_score: r.final_score || r.similarity, // Falls back to similarity if no recency
+            retrieval_score: r.similarity ?? null,
+            // Graph metadata (NEW - Phase 1)
+            graph_source: r.graph_source || 'primary',
+            graph_rank: r.graph_rank || 1.0,
+            related_to: r.related_to || null,
+            edge_reason: r.edge_reason || null,
+            case_id: null,
+            source_type: 'decision',
+        }));
+        const { results: rankedVectorRows, meta: rankerMeta } = applyLearnedRanker(vectorRows);
+        const finalResults = rankedVectorRows.slice(0, limit);
         // Markdown format (for human display)
         if (format === 'markdown') {
             const context = (0, decision_formatter_js_1.formatContext)(finalResults, { maxTokens: 500 });
@@ -976,27 +1332,9 @@ async function suggest(userQuestion, options = {}) {
                 contradicts: finalResults.filter((r) => r.graph_source === 'contradicts').length,
             },
         };
-        // JSON format (default - LLM-first)
         return {
             query: userQuestion,
-            results: finalResults.map((r) => ({
-                id: r.id,
-                topic: r.topic,
-                decision: r.decision,
-                reasoning: r.reasoning,
-                confidence: r.confidence,
-                similarity: r.similarity,
-                created_at: r.created_at,
-                // Recency metadata (NEW - Gaussian Decay)
-                recency_score: r.recency_score,
-                recency_age_days: r.recency_age_days,
-                final_score: r.final_score || r.similarity, // Falls back to similarity if no recency
-                // Graph metadata (NEW - Phase 1)
-                graph_source: r.graph_source || 'primary',
-                graph_rank: r.graph_rank || 1.0,
-                related_to: r.related_to || null,
-                edge_reason: r.edge_reason || null,
-            })),
+            results: finalResults,
             meta: {
                 count: finalResults.length,
                 search_method: searchMethod,
@@ -1011,6 +1349,7 @@ async function suggest(userQuestion, options = {}) {
                     },
                 // Graph expansion stats (NEW - Phase 1)
                 graph_expansion: searchMethod.includes('graph') ? graphStats : null,
+                ranker: rankerMeta,
             },
         };
     }
@@ -1068,7 +1407,7 @@ async function listDecisions(options = {}) {
         JOIN memory_scope_bindings msb ON msb.memory_id = d.id
         WHERE msb.scope_id IN (${placeholders})
           AND d.superseded_by IS NULL
-        ORDER BY d.created_at DESC
+        ORDER BY COALESCE(d.event_datetime, d.created_at) DESC, d.created_at DESC
         LIMIT ?
       `);
             decisions = await stmt.all(...scopeIds, limit);
@@ -1077,7 +1416,7 @@ async function listDecisions(options = {}) {
             const stmt = adapter.prepare(`
         SELECT * FROM decisions
         WHERE superseded_by IS NULL
-        ORDER BY created_at DESC
+        ORDER BY COALESCE(event_datetime, created_at) DESC, created_at DESC
         LIMIT ?
       `);
             decisions = await stmt.all(limit);
@@ -2359,14 +2698,19 @@ function formatQualityReportMarkdown(report) {
 const mama = {
     // Core functions (used by 4 MCP tools)
     save,
+    saveWithTrustedProvenance,
     suggest,
     saveMemory: api_js_1.saveMemory,
+    saveMemoryWithTrustedProvenance: api_js_1.saveMemoryWithTrustedProvenance,
     recallMemory: api_js_1.recallMemory,
     list: listDecisions,
     listCheckpoints,
     updateOutcome,
     buildProfile: api_js_1.buildProfile,
     ingestMemory: api_js_1.ingestMemory,
+    ingestWithTrustedProvenance: api_js_1.ingestWithTrustedProvenance,
+    ingestConversation: api_js_1.ingestConversation,
+    ingestConversationWithTrustedProvenance: api_js_1.ingestConversationWithTrustedProvenance,
     evolveMemory: api_js_1.evolveMemory,
     buildMemoryBootstrap: api_js_1.buildMemoryBootstrap,
     createAuditAck: api_js_1.createAuditAck,
@@ -2374,7 +2718,22 @@ const mama = {
     upsertChannelSummary: api_js_1.upsertChannelSummary,
     getChannelSummary: api_js_1.getChannelSummary,
     listAuditFindings: finding_store_js_1.listOpenAuditFindings,
+    getMemoryProvenance: provenance_query_js_1.getMemoryProvenance,
+    listMemoriesByEnvelopeHash: provenance_query_js_1.listMemoriesByEnvelopeHash,
+    listMemoriesByGatewayCallId: provenance_query_js_1.listMemoriesByGatewayCallId,
+    listMemoriesByModelRunId: provenance_query_js_1.listMemoriesByModelRunId,
+    listMemoryEventsForMemory: event_store_js_1.listMemoryEventsForMemory,
     listRecentMemoryEvents: event_store_js_1.listRecentMemoryEvents,
+    beginModelRun: store_js_1.beginModelRun,
+    beginModelRunInAdapter: store_js_1.beginModelRunInAdapter,
+    commitModelRun: store_js_1.commitModelRun,
+    commitModelRunInAdapter: store_js_1.commitModelRunInAdapter,
+    failModelRun: store_js_1.failModelRun,
+    failModelRunInAdapter: store_js_1.failModelRunInAdapter,
+    getModelRun: store_js_1.getModelRun,
+    getModelRunInAdapter: store_js_1.getModelRunInAdapter,
+    appendToolTrace: tool_trace_store_js_1.appendToolTrace,
+    listToolTracesForRun: tool_trace_store_js_1.listToolTracesForRun,
     saveCheckpoint,
     loadCheckpoint,
     // Legacy functions (retained for internal use, not exposed via MCP)