@jungjaehoon/mama-core 1.5.0 → 1.6.0

package/dist/memory/api.js

@@ -7,15 +7,18 @@ exports.getChannelSummary = exports.upsertChannelSummary = exports.LEXICAL_STOPW
 exports.getLexicalQueryTokens = getLexicalQueryTokens;
 exports.loadEdgesForIds = loadEdgesForIds;
 exports.saveMemory = saveMemory;
+exports.saveMemoryWithTrustedProvenance = saveMemoryWithTrustedProvenance;
 exports.buildProfile = buildProfile;
 exports.recallMemory = recallMemory;
 exports.ingestMemory = ingestMemory;
+exports.ingestWithTrustedProvenance = ingestWithTrustedProvenance;
 exports.evolveMemory = evolveMemory;
 exports.buildMemoryBootstrap = buildMemoryBootstrap;
 exports.createAuditAck = createAuditAck;
 exports.recordMemoryAudit = recordMemoryAudit;
 exports.setExtractionFn = setExtractionFn;
 exports.ingestConversation = ingestConversation;
+exports.ingestConversationWithTrustedProvenance = ingestConversationWithTrustedProvenance;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const db_manager_js_1 = require("../db-manager.js");
 const embeddings_js_1 = require("../embeddings.js");
@@ -33,10 +36,23 @@ Object.defineProperty(exports, "getChannelSummary", { enumerable: true, get: fun
 Object.defineProperty(exports, "upsertChannelSummary", { enumerable: true, get: function () { return channel_summary_store_js_1.upsertChannelSummary; } });
 const recall_bridge_js_1 = require("../entities/recall-bridge.js");
 const read_identity_js_1 = require("../entities/read-identity.js");
+const search_quality_js_1 = require("../search/search-quality.js");
+const event_store_js_1 = require("./event-store.js");
+const provenance_js_1 = require("./provenance.js");
 function buildDecisionId(topic) {
     const safeTopic = topic.replace(/[^a-z0-9_]+/gi, '_').toLowerCase();
     return `decision_${safeTopic}_${Date.now()}_${node_crypto_1.default.randomUUID().slice(0, 8)}`;
 }
+function buildSaveEventReason(toolName, gatewayCallId) {
+    const parts = ['saved'];
+    if (toolName) {
+        parts.push(`via ${toolName}`);
+    }
+    if (gatewayCallId) {
+        parts.push(`gateway_call_id=${gatewayCallId}`);
+    }
+    return parts.join(' ');
+}
 function toMemoryRecord(row, scopes, fallbackSource) {
     let trustContext = null;
     if (typeof row.trust_context === 'string') {
@@ -304,6 +320,19 @@ function getLexicalQueryTokens(query) {
         .split(/[\s,.!?;:()[\]{}"']+/)
         .filter((token) => token.length > 2 && !exports.LEXICAL_STOPWORDS.has(token));
 }
+function queryTokenCount(query) {
+    const lexicalTokens = getLexicalQueryTokens(query);
+    if (lexicalTokens.length > 0) {
+        return lexicalTokens.length;
+    }
+    return query.trim().split(/\s+/).filter(Boolean).length;
+}
+function looksMixedKoreanEnglish(query) {
+    return /[\uac00-\ud7a3]/.test(query) && /[a-z]/i.test(query);
+}
+function looksEntityLike(query) {
+    return /\b[A-Z][A-Za-z0-9_-]{2,}\b/.test(query) || /[#/][A-Za-z0-9_-]{2,}/.test(query);
+}
 function buildLexicalCandidates(records, query) {
     const tokens = getLexicalQueryTokens(query);
     const normalizedQuery = query.toLowerCase();
@@ -407,11 +436,12 @@ async function loadEdgesForIds(ids) {
         reason: row.reason ?? undefined,
     }));
 }
-async function saveMemory(input) {
+async function saveMemoryInternal(input, options) {
     await (0, db_manager_js_1.initDB)();
     const adapter = (0, db_manager_js_1.getAdapter)();
     const id = buildDecisionId(input.topic);
     const now = Date.now();
+    const provenance = (0, provenance_js_1.normalizeMemoryWriteProvenance)(options);
     // Find evolution candidates: exact topic match first, then semantic search fallback
     const primaryScope = input.scopes.length > 0 ? input.scopes[0] : null;
     const excludeIds = new Set(input.excludeIds ?? []);
@@ -504,6 +534,12 @@ async function saveMemory(input) {
         trust_context: JSON.stringify({ source: input.source }),
         event_date: input.eventDate ?? null,
         event_datetime: eventDateTime,
+        agent_id: provenance.agent_id,
+        model_run_id: provenance.model_run_id,
+        envelope_hash: provenance.envelope_hash,
+        gateway_call_id: provenance.gateway_call_id,
+        source_refs_json: JSON.stringify(provenance.source_refs),
+        provenance_json: JSON.stringify(provenance.provenance),
     });
     // Pre-resolve scope IDs before the synchronous transaction
     const resolvedScopeIds = [];
@@ -529,6 +565,17 @@ async function saveMemory(input) {
             `)
                     .run(id, scopeId, isPrimary ? 1 : 0);
             }
+            (0, event_store_js_1.insertMemoryEventInTransaction)(adapter, {
+                event_type: 'save',
+                actor: provenance.actor,
+                source_turn_id: provenance.source_turn_id ?? undefined,
+                memory_id: id,
+                topic: input.topic,
+                scope_refs: input.scopes,
+                evidence_refs: provenance.source_refs,
+                reason: buildSaveEventReason(provenance.tool_name, provenance.gateway_call_id),
+                created_at: now,
+            });
             for (const entityObservationId of entityObservationIds) {
                 adapter
                     .prepare(`
@@ -587,6 +634,12 @@ async function saveMemory(input) {
         timeline_event_ids: timelineEvent ? [timelineEvent.id] : [],
     };
 }
+async function saveMemory(input) {
+    return saveMemoryInternal((0, provenance_js_1.sanitizePublicSaveMemoryInput)(input));
+}
+async function saveMemoryWithTrustedProvenance(input, options) {
+    return saveMemoryInternal((0, provenance_js_1.sanitizePublicSaveMemoryInput)(input), options);
+}
 async function buildProfile(scopes) {
     const records = await loadScopedMemories(scopes);
     return (0, profile_builder_js_1.classifyProfileEntries)(records);
@@ -599,10 +652,26 @@ const EXCLUDED_STATUSES = new Set([
 ]);
 async function recallMemory(query, options = {}) {
     const bundle = (0, types_js_1.createEmptyRecallBundle)(query);
+    const searchOptions = (0, search_quality_js_1.normalizeSearchQualityOptions)(options);
+    const diagnostics = {
+        candidate_counts: {
+            vector: 0,
+            lexical: 0,
+            entity: 0,
+            graph_expanded: 0,
+            vector_only: 0,
+            rejected_by_strictness: 0,
+        },
+        threshold: searchOptions.threshold,
+        strictness: searchOptions.strictness,
+    };
     let matched = [];
     let fusedHits = [];
     let retrievalSource = 'none';
     const projectionMode = process.env.MAMA_ENTITY_PROJECTION_MODE ?? 'shadow';
+    const vectorSimilarityById = new Map();
+    const lexicalScoreById = new Map();
+    const entitySupportIds = new Set();
     let _lexicalRecords = null;
     const loadLexical = async () => {
         if (_lexicalRecords === null) {
@@ -639,14 +708,15 @@ async function recallMemory(query, options = {}) {
             if (sq === query && primaryQueryEmbedding === null) {
                 primaryQueryEmbedding = queryEmbedding;
             }
-            const vectorResults = await (0, db_manager_js_1.vectorSearch)(queryEmbedding, vectorLimit, 0.3, options.topicPrefix);
+            const vectorResults = await (0, db_manager_js_1.vectorSearch)(queryEmbedding, vectorLimit, searchOptions.threshold, searchOptions.topicPrefix);
             let filtered = vectorResults;
+            let vectorScopeMap = new Map();
             if (options.scopes && options.scopes.length > 0) {
                 const vectorIds = vectorResults.map((r) => String(r.id));
-                const scopeMap = batchLoadScopes((0, db_manager_js_1.getAdapter)(), vectorIds);
+                vectorScopeMap = batchLoadScopes((0, db_manager_js_1.getAdapter)(), vectorIds);
                 const requestedScopes = new Set(options.scopes.map((s) => `${s.kind}:${s.id}`));
                 filtered = vectorResults.filter((r) => {
-                    const scopes = scopeMap.get(String(r.id)) ?? [];
+                    const scopes = vectorScopeMap.get(String(r.id)) ?? [];
                     // When scopes are requested, zero-binding results must NOT pass through
                     if (scopes.length === 0)
                         return false;
@@ -666,13 +736,17 @@ async function recallMemory(query, options = {}) {
                     details: String(result.reasoning || ''),
                     confidence: result.similarity ?? 0.5,
                     status: effectiveStatus || 'active',
-                    scopes: [],
+                    scopes: vectorScopeMap.get(String(result.id)) ?? [],
                     source: { package: 'mama-core', source_type: 'vector_search' },
                     created_at: result.created_at ?? Date.now(),
                     updated_at: result.created_at ?? Date.now(),
                     event_date: result.event_date ?? null,
                     event_datetime: result.event_datetime ?? null,
                 });
+                diagnostics.candidate_counts.vector += 1;
+                if (typeof result.similarity === 'number' && Number.isFinite(result.similarity)) {
+                    vectorSimilarityById.set(String(result.id), result.similarity);
+                }
             }
         } // end sub-query loop
     }
@@ -694,7 +768,14 @@ async function recallMemory(query, options = {}) {
     // Lazy lexical: skip expensive FTS5/lexical when vector already returned enough results,
     // unless this is an aggregation query that benefits from broader coverage.
     const VECTOR_SUFFICIENT_THRESHOLD = 5;
-    const needsLexical = isAggregation || vectorMatched.length < VECTOR_SUFFICIENT_THRESHOLD;
+    const shouldForceLexicalConfirmation = searchOptions.strictness !== 'recall' ||
+        searchOptions.minLexicalSupport ||
+        queryTokenCount(query) <= 3 ||
+        looksMixedKoreanEnglish(query) ||
+        looksEntityLike(query);
+    const needsLexical = isAggregation ||
+        vectorMatched.length < VECTOR_SUFFICIENT_THRESHOLD ||
+        shouldForceLexicalConfirmation;
     let lexicalCandidates = [];
     const lexicalLimit = isAggregation ? 100 : 50;
     if (needsLexical) {
@@ -766,7 +847,7 @@ async function recallMemory(query, options = {}) {
                     const scopeMap = batchLoadScopes(adapter, memoryIds);
                     const record = toMemoryRecord(row, scopeMap.get(String(row.id)) ?? [], fallbackSource);
                     // Topic prefix filtering (matches vectorSearch behavior)
-                    if (options.topicPrefix && !record.topic.startsWith(options.topicPrefix))
+                    if (searchOptions.topicPrefix && !record.topic.startsWith(searchOptions.topicPrefix))
                         continue;
                     // Scope filtering
                     if (options.scopes && options.scopes.length > 0) {
@@ -800,8 +881,8 @@ async function recallMemory(query, options = {}) {
                 });
             }
             // Topic prefix filtering for in-memory lexical (matches vectorSearch behavior)
-            if (options.topicPrefix) {
-                lexicalRecords = lexicalRecords.filter((r) => r.topic.startsWith(options.topicPrefix));
+            if (searchOptions.topicPrefix) {
+                lexicalRecords = lexicalRecords.filter((r) => r.topic.startsWith(searchOptions.topicPrefix));
             }
             lexicalCandidates = buildLexicalCandidates(lexicalRecords, query);
             if (subQueries.length > 1) {
@@ -817,6 +898,10 @@ async function recallMemory(query, options = {}) {
             }
         }
     } // end needsLexical
+    diagnostics.candidate_counts.lexical = lexicalCandidates.length;
+    for (const candidate of lexicalCandidates) {
+        lexicalScoreById.set(candidate.memory.id, candidate.score);
+    }
     // RRF Fusion: combine vector and lexical/FTS5 results by reciprocal rank
     // FTS5 BM25 gets 2x weight — it naturally demotes records where query terms
     // appear only in passing (e.g. "wedding" mentioned once in a dating record),
@@ -861,6 +946,7 @@ async function recallMemory(query, options = {}) {
     let hasWikiHits = false;
     const wikiScores = new Map();
     const wikiVectorRankMap = new Map();
+    const wikiVectorScoreById = new Map();
     try {
         const adapter = (0, db_manager_js_1.getAdapter)();
         const wikiFtsHits = (0, wiki_page_index_js_1.ftsSearchWikiPages)(adapter, query, requestedLimit * 2);
@@ -875,7 +961,10 @@ async function recallMemory(query, options = {}) {
         }
         for (let i = 0; i < wikiVectorHits.length; i++) {
             wikiVectorRankMap.set(wikiVectorHits[i].record.id, i);
+            wikiVectorScoreById.set(wikiVectorHits[i].record.id, wikiVectorHits[i].raw_score);
         }
+        diagnostics.candidate_counts.lexical += wikiFtsHits.length;
+        diagnostics.candidate_counts.vector += wikiVectorHits.length;
         for (let i = 0; i < wikiFtsHits.length; i++) {
             const hit = wikiFtsHits[i];
             const lexScore = 1 / (RRF_K + i + 1);
@@ -884,6 +973,8 @@ async function recallMemory(query, options = {}) {
             wikiScores.set(hit.record.id, {
                 record: hit.record,
                 score: lexScore + vecBoost,
+                lexicalSupport: true,
+                vectorSimilarity: wikiVectorScoreById.get(hit.record.id) ?? null,
             });
         }
         for (let i = 0; i < wikiVectorHits.length; i++) {
@@ -894,24 +985,15 @@ async function recallMemory(query, options = {}) {
             wikiScores.set(hit.record.id, {
                 record: hit.record,
                 score: 0.15 * (1 / (RRF_K + i + 1)),
+                lexicalSupport: false,
+                vectorSimilarity: hit.raw_score,
             });
         }
-        hasWikiHits = wikiScores.size > 0;
     }
     catch (wikiFtsErr) {
         (0, debug_logger_js_1.warn)(`[recallMemory] Wiki FTS search failed: ${wikiFtsErr instanceof Error ? wikiFtsErr.message : String(wikiFtsErr)}`);
     }
-    const wikiFusedHits = Array.from(wikiScores.values())
-        .sort((a, b) => b.score - a.score)
-        .map((entry) => ({
-        source_type: 'wiki_page',
-        source_id: entry.record.source_locator,
-        record: entry.record,
-        fused_rank_score: entry.score,
-        ...(entry.record.page_type === 'case' ? { page_type: 'case' } : {}),
-        ...(entry.record.case_id ? { case_id: entry.record.case_id } : {}),
-    }));
-    fusedHits = [...decisionFusedHits, ...wikiFusedHits].sort((left, right) => right.fused_rank_score - left.fused_rank_score);
+    fusedHits = decisionFusedHits;
     // Normalize RRF scores to 0-1 range so downstream consumers (threshold filters,
     // similarity displays) get meaningful values.  The raw RRF score for K=60 tops out
     // around 0.033, which is misleading when compared against similarity thresholds.
@@ -929,13 +1011,14 @@ async function recallMemory(query, options = {}) {
     else if (lexicalCandidates.length > 0) {
         retrievalSource = 'lexical_search';
     }
-    if (hasWikiHits) {
-        retrievalSource = retrievalSource === 'none' ? 'wiki_page' : `${retrievalSource}+wiki_page`;
-    }
     let canonicalMatched = [];
     if (projectionMode !== 'off') {
         try {
             canonicalMatched = await (0, recall_bridge_js_1.queryCanonicalEntities)(query, options.scopes ?? [], { limit: 10 });
+            diagnostics.candidate_counts.entity = canonicalMatched.length;
+            for (const canonical of canonicalMatched) {
+                entitySupportIds.add(canonical.id);
+            }
             if (projectionMode === 'dual-write' && canonicalMatched.length > 0) {
                 const seenIds = new Set(matched.map((item) => item.id));
                 for (const canonical of canonicalMatched) {
@@ -956,6 +1039,318 @@ async function recallMemory(query, options = {}) {
             (0, debug_logger_js_1.warn)(`[recallMemory] Canonical entity recall failed: ${canonicalErr instanceof Error ? canonicalErr.message : String(canonicalErr)}`);
         }
     }
+    const requestedScopeKeys = new Set((options.scopes ?? []).map((scope) => `${scope.kind}:${scope.id}`));
+    const hasRequestedScopeSupport = (record) => {
+        if (requestedScopeKeys.size === 0) {
+            return true;
+        }
+        return record.scopes.some((scope) => requestedScopeKeys.has(`${scope.kind}:${scope.id}`));
+    };
+    // exact_topic confirmation is intentionally narrow: short substring matches
+    // would let two-letter queries like "ai" trip on words like "email" and
+    // promote vector-only hits past strict/balanced rejection. Require either
+    // exact equality or whole-token containment, and ignore tiny queries.
+    const EXACT_TOPIC_MIN_QUERY_LENGTH = 3;
+    const tokenizeForExactTopic = (input) => input.split(/[^a-z0-9]+/).filter((token) => token.length > 0);
+    const hasExactTopicSupport = (record) => {
+        const normalizedQuery = query.trim().toLowerCase();
+        const normalizedTopic = record.topic.trim().toLowerCase();
+        if (!normalizedQuery || !normalizedTopic) {
+            return false;
+        }
+        if (normalizedQuery.length < EXACT_TOPIC_MIN_QUERY_LENGTH) {
+            return false;
+        }
+        if (normalizedQuery === normalizedTopic) {
+            return true;
+        }
+        const queryTokens = tokenizeForExactTopic(normalizedQuery);
+        const topicTokens = tokenizeForExactTopic(normalizedTopic);
+        // Whole-token match: a topic word equals the entire query, OR the topic
+        // (when itself a single token) appears as a complete word in the query.
+        return topicTokens.includes(normalizedQuery) || queryTokens.includes(normalizedTopic);
+    };
+    const hasExactWikiSupport = (record) => {
+        const normalizedQuery = query.trim().toLowerCase();
+        if (!normalizedQuery || normalizedQuery.length < EXACT_TOPIC_MIN_QUERY_LENGTH) {
+            return false;
+        }
+        const normalizedTitle = record.title.trim().toLowerCase();
+        if (!normalizedTitle) {
+            return false;
+        }
+        if (normalizedQuery === normalizedTitle) {
+            return true;
+        }
+        const queryTokens = tokenizeForExactTopic(normalizedQuery);
+        const titleTokens = tokenizeForExactTopic(normalizedTitle);
+        // Wiki exact_topic uses TITLE only — page body matches are too lenient
+        // for an "exact" signal and remain available through other diagnostics.
+        return titleTokens.includes(normalizedQuery) || queryTokens.includes(normalizedTitle);
+    };
+    const wikiDecisionIdCache = new Map();
+    const normalizeWikiDecisionSourceId = (sourceId) => {
+        const trimmed = sourceId.trim();
+        if (!trimmed) {
+            return null;
+        }
+        if (trimmed.startsWith('decision://')) {
+            const id = trimmed.slice('decision://'.length).trim();
+            return id || null;
+        }
+        if (trimmed.startsWith('decision:')) {
+            const id = trimmed.slice('decision:'.length).trim();
+            return id || null;
+        }
+        if (/^[A-Za-z][A-Za-z0-9_-]*:/.test(trimmed)) {
+            return null;
+        }
+        return trimmed;
+    };
+    const loadWikiDecisionIds = (record) => {
+        const cached = wikiDecisionIdCache.get(record.id);
+        if (cached) {
+            return cached;
+        }
+        const ids = new Set();
+        for (const sourceId of record.source_ids) {
+            const decisionId = normalizeWikiDecisionSourceId(sourceId);
+            if (decisionId) {
+                ids.add(decisionId);
+            }
+        }
+        if (record.case_id) {
+            const rows = (0, db_manager_js_1.getAdapter)()
+                .prepare(`
+            SELECT source_id
+            FROM case_memberships
+            WHERE case_id = ?
+              AND source_type = 'decision'
+              AND status = 'active'
+          `)
+                .all(record.case_id);
+            for (const row of rows) {
+                if (row.source_id) {
+                    ids.add(row.source_id);
+                }
+            }
+        }
+        const decisionIds = Array.from(ids);
+        wikiDecisionIdCache.set(record.id, decisionIds);
+        return decisionIds;
+    };
+    const wikiScopeSupportCache = new Map();
+    const hasRequestedWikiScopeSupport = (record) => {
+        if (requestedScopeKeys.size === 0) {
+            return true;
+        }
+        const cached = wikiScopeSupportCache.get(record.id);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const decisionIds = loadWikiDecisionIds(record);
+        if (decisionIds.length === 0) {
+            wikiScopeSupportCache.set(record.id, false);
+            return false;
+        }
+        const scopeMap = batchLoadScopes((0, db_manager_js_1.getAdapter)(), decisionIds);
+        const supported = decisionIds.some((id) => (scopeMap.get(id) ?? []).some((scope) => requestedScopeKeys.has(`${scope.kind}:${scope.id}`)));
+        wikiScopeSupportCache.set(record.id, supported);
+        return supported;
+    };
+    // Combined check used for the wiki *filter* path: a wiki entry must have at
+    // least one linked decision that matches BOTH the requested scope AND the
+    // requested topicPrefix. Without this, the page passes when scope matches
+    // decision A and topic matches decision B — i.e., neither single decision
+    // satisfies the caller's filter. Diagnostics reporting (which only signals
+    // scope confirmation) keeps using hasRequestedWikiScopeSupport.
+    const wikiCombinedSupportCache = new Map();
+    const hasWikiDecisionWithScopeAndTopic = (record) => {
+        const requiresScope = requestedScopeKeys.size > 0;
+        const requiresTopic = !!searchOptions.topicPrefix;
+        if (!requiresScope && !requiresTopic) {
+            return true;
+        }
+        const cached = wikiCombinedSupportCache.get(record.id);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const decisionIds = loadWikiDecisionIds(record);
+        if (decisionIds.length === 0) {
+            wikiCombinedSupportCache.set(record.id, false);
+            return false;
+        }
+        const adapter = (0, db_manager_js_1.getAdapter)();
+        const scopeMap = requiresScope ? batchLoadScopes(adapter, decisionIds) : null;
+        const topicByDecisionId = new Map();
+        if (requiresTopic) {
+            const IN_CHUNK_SIZE = 900;
+            for (let i = 0; i < decisionIds.length; i += IN_CHUNK_SIZE) {
+                const chunk = decisionIds.slice(i, i + IN_CHUNK_SIZE);
+                const placeholders = chunk.map(() => '?').join(', ');
+                const rows = adapter
+                    .prepare(`SELECT id, topic FROM decisions WHERE id IN (${placeholders})`)
+                    .all(...chunk);
+                for (const row of rows) {
+                    topicByDecisionId.set(row.id, String(row.topic ?? ''));
+                }
+            }
+        }
+        const supported = decisionIds.some((id) => {
+            if (requiresScope) {
+                const scopes = scopeMap?.get(id) ?? [];
+                const scopeOk = scopes.some((scope) => requestedScopeKeys.has(`${scope.kind}:${scope.id}`));
+                if (!scopeOk) {
+                    return false;
+                }
+            }
+            if (requiresTopic) {
+                const topic = topicByDecisionId.get(id) ?? '';
+                if (!topic.startsWith(searchOptions.topicPrefix)) {
+                    return false;
+                }
+            }
+            return true;
+        });
+        wikiCombinedSupportCache.set(record.id, supported);
+        return supported;
+    };
+    const buildDiagnostics = (record, graphSource) => {
+        const vectorSimilarity = vectorSimilarityById.get(record.id) ?? null;
+        const lexicalSupport = lexicalScoreById.has(record.id);
+        const entitySupport = entitySupportIds.has(record.id);
+        const exactTopicSupport = hasExactTopicSupport(record);
+        const scopeSupport = hasRequestedScopeSupport(record);
+        const confirmationSignals = [
+            lexicalSupport ? 'lexical' : null,
+            entitySupport ? 'entity' : null,
+            exactTopicSupport ? 'exact_topic' : null,
+        ].filter((signal) => signal !== null);
+        const metadataSignals = [
+            requestedScopeKeys.size > 0 && scopeSupport ? 'scope' : null,
+            graphSource === 'primary' ? 'graph_primary' : null,
+            graphSource === 'expanded' ? 'graph_expanded' : null,
+        ].filter((signal) => signal !== null);
+        const retrievalSourceForRecord = vectorSimilarity !== null && lexicalSupport
+            ? 'hybrid_rrf'
+            : vectorSimilarity !== null
+                ? 'vector_search'
+                : lexicalSupport
+                    ? 'lexical_search'
+                    : entitySupport
+                        ? 'entity_canonical'
+                        : String(record.source.source_type || 'unknown');
+        return {
+            retrieval_source: retrievalSourceForRecord,
+            vector_similarity: vectorSimilarity,
+            lexical_support: lexicalSupport,
+            entity_support: entitySupport,
+            scope_support: scopeSupport,
+            graph_source: graphSource,
+            is_vector_only: vectorSimilarity !== null && confirmationSignals.length === 0,
+            confirmation_signals: confirmationSignals,
+            metadata_signals: metadataSignals,
+            candidate_threshold_used: searchOptions.threshold,
+        };
+    };
+    const buildWikiDiagnostics = (entry) => {
+        const lexicalSupport = entry.lexicalSupport;
+        const exactTopicSupport = hasExactWikiSupport(entry.record);
+        const scopeSupport = hasRequestedWikiScopeSupport(entry.record);
+        const confirmationSignals = [
+            lexicalSupport ? 'lexical' : null,
+            exactTopicSupport ? 'exact_topic' : null,
+        ].filter((signal) => signal !== null);
+        // Only attribute 'scope' when the caller actually requested a scope filter.
+        // hasRequestedWikiScopeSupport() returns true by default for unscoped searches,
+        // so without this guard the diagnostics would overstate why the wiki hit passed.
+        const metadataSignals = [
+            requestedScopeKeys.size > 0 && scopeSupport ? 'scope' : null,
+            'graph_primary',
+        ].filter((signal) => signal !== null);
+        const retrievalSourceForRecord = entry.vectorSimilarity !== null && lexicalSupport
+            ? 'wiki_hybrid_rrf'
+            : entry.vectorSimilarity !== null
+                ? 'wiki_vector_search'
+                : lexicalSupport
+                    ? 'wiki_lexical_search'
+                    : 'wiki_page';
+        return {
+            retrieval_source: retrievalSourceForRecord,
+            vector_similarity: entry.vectorSimilarity,
+            lexical_support: lexicalSupport,
+            entity_support: false,
+            scope_support: scopeSupport,
+            graph_source: 'primary',
+            is_vector_only: entry.vectorSimilarity !== null && confirmationSignals.length === 0,
+            confirmation_signals: confirmationSignals,
+            metadata_signals: metadataSignals,
+            candidate_threshold_used: searchOptions.threshold,
+        };
+    };
+    const passesStrictness = (hitDiagnostics) => {
+        if (searchOptions.strictness === 'recall') {
+            return true;
+        }
+        if (hitDiagnostics.confirmation_signals.length === 0) {
+            return false;
+        }
+        if (!searchOptions.minLexicalSupport) {
+            return true;
+        }
+        return (hitDiagnostics.lexical_support ||
+            hitDiagnostics.entity_support ||
+            hitDiagnostics.confirmation_signals.includes('exact_topic'));
+    };
+    const acceptedPrimaryIds = new Set();
+    matched = matched.flatMap((record) => {
+        const recordDiagnostics = buildDiagnostics(record, 'primary');
+        if (recordDiagnostics.is_vector_only) {
+            diagnostics.candidate_counts.vector_only += 1;
+        }
+        if (!passesStrictness(recordDiagnostics)) {
+            diagnostics.candidate_counts.rejected_by_strictness += 1;
+            return [];
+        }
+        acceptedPrimaryIds.add(record.id);
+        return [
+            searchOptions.diagnostics ? { ...record, retrieval_diagnostics: recordDiagnostics } : record,
+        ];
+    });
+    fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || acceptedPrimaryIds.has(hit.source_id));
+    const acceptedWikiFusedHits = Array.from(wikiScores.values())
+        .sort((a, b) => b.score - a.score)
+        .flatMap((entry) => {
+        if (!hasWikiDecisionWithScopeAndTopic(entry.record)) {
+            return [];
+        }
+        const wikiDiagnostics = buildWikiDiagnostics(entry);
+        if (wikiDiagnostics.is_vector_only) {
+            diagnostics.candidate_counts.vector_only += 1;
+        }
+        if (!passesStrictness(wikiDiagnostics)) {
+            diagnostics.candidate_counts.rejected_by_strictness += 1;
+            return [];
+        }
+        return [
+            {
+                source_type: 'wiki_page',
+                source_id: entry.record.source_locator,
+                record: searchOptions.diagnostics
+                    ? { ...entry.record, retrieval_diagnostics: wikiDiagnostics }
+                    : entry.record,
+                fused_rank_score: entry.score,
+                ...(searchOptions.diagnostics ? { retrieval_diagnostics: wikiDiagnostics } : {}),
+                ...(entry.record.page_type === 'case' ? { page_type: 'case' } : {}),
+                ...(entry.record.case_id ? { case_id: entry.record.case_id } : {}),
+            },
+        ];
+    });
+    hasWikiHits = acceptedWikiFusedHits.length > 0;
+    fusedHits = [...fusedHits, ...acceptedWikiFusedHits].sort((left, right) => right.fused_rank_score - left.fused_rank_score);
+    if (hasWikiHits) {
+        retrievalSource = retrievalSource === 'none' ? 'wiki_page' : `${retrievalSource}+wiki_page`;
+    }
     if (matched.length > 0) {
         const readIdentityIndex = await (0, read_identity_js_1.loadDecisionReadIdentityIndex)(matched.filter((record) => !record.read_identity).map((record) => record.id));
         for (const record of matched) {
@@ -991,7 +1386,7 @@ async function recallMemory(query, options = {}) {
     bundle.graph_context.primary = matched;
     bundle.graph_context.expanded = [];
     bundle.graph_context.edges = [];
-    if (matched.length > 0 && !options.skipGraphExpansion) {
+    if (matched.length > 0 && !options.skipGraphExpansion && searchOptions.includeRelated) {
         try {
             const candidates = matched.map((m) => ({
                 id: m.id,
@@ -1006,6 +1401,7 @@ async function recallMemory(query, options = {}) {
             const expanded = await mamaDefault.expandWithGraph(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) => {
@@ -1017,32 +1413,63 @@ async function recallMemory(query, options = {}) {
             }
             if (options.scopes && options.scopes.length > 0) {
                 const expandedIds = expandedOnly.map((e) => e.id);
-                const scopeMap = batchLoadScopes((0, db_manager_js_1.getAdapter)(), expandedIds);
+                expandedScopeMap = batchLoadScopes((0, db_manager_js_1.getAdapter)(), expandedIds);
                 const requestedScopes = new Set(options.scopes.map((s) => `${s.kind}:${s.id}`));
                 expandedOnly = expandedOnly.filter((e) => {
-                    const scopes = scopeMap.get(e.id) ?? [];
+                    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.map((e) => ({
-                id: String(e.id),
-                topic: String(e.topic || ''),
-                kind: 'decision',
-                summary: String(e.decision || ''),
-                details: '',
-                confidence: e.graph_rank ?? 0.5,
-                status: 'active',
-                scopes: [],
-                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 allIds = [...matched.map((m) => m.id), ...expandedOnly.map((e) => e.id)];
+            bundle.graph_context.expanded = expandedOnly.flatMap((e) => {
+                const expandedRecord = {
+                    id: String(e.id),
+                    topic: String(e.topic || ''),
+                    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,
+                ];
+            });
+            diagnostics.candidate_counts.graph_expanded = bundle.graph_context.expanded.length;
+            fusedHits = [
+                ...fusedHits,
+                ...bundle.graph_context.expanded.map((record) => ({
+                    source_type: 'decision',
+                    source_id: record.id,
+                    record,
+                    fused_rank_score: (record.confidence ?? 0.5) * 0.1,
+                    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(allIds);
             // Filter out edges pointing to decisions with excluded statuses
             const activeIds = new Set(allIds);
@@ -1070,14 +1497,17 @@ async function recallMemory(query, options = {}) {
     bundle.fused_hits = fusedHits;
     bundle.search_meta.scope_order = (options.scopes ?? []).map((scope) => scope.kind);
     bundle.search_meta.retrieval_sources = [retrievalSource];
+    if (searchOptions.diagnostics) {
+        bundle.search_meta.diagnostics = diagnostics;
+    }
     if (options.includeProfile) {
         bundle.profile = await buildProfile(options.scopes ?? []);
     }
     return bundle;
 }
-async function ingestMemory(input) {
+async function ingestMemoryInternal(input, options) {
     const normalized = input.content.trim();
-    return saveMemory({
+    return saveMemoryInternal({
         topic: normalized
             .slice(0, 40)
             .toLowerCase()
@@ -1090,7 +1520,13 @@ async function ingestMemory(input) {
         source: input.source,
         eventDate: input.eventDate,
         eventDateTime: input.eventDateTime,
-    });
+    }, options);
+}
+async function ingestMemory(input) {
+    return ingestMemoryInternal((0, provenance_js_1.sanitizePublicIngestMemoryInput)(input));
+}
+async function ingestWithTrustedProvenance(input, options) {
+    return ingestMemoryInternal((0, provenance_js_1.sanitizePublicIngestMemoryInput)(input), options);
 }
 async function evolveMemory(input) {
     return (0, evolution_engine_js_1.resolveMemoryEvolution)(input);
@@ -1142,18 +1578,18 @@ let extractionFn = callExtractionLLM;
 function setExtractionFn(fn) {
     extractionFn = fn ?? callExtractionLLM;
 }
-async function ingestConversation(input) {
+async function ingestConversationInternal(input, options) {
     if (!input.messages || input.messages.length === 0) {
         throw new Error('messages array must not be empty');
     }
     const conversationText = input.messages.map((m) => `${m.role}: ${m.content}`).join('\n');
     const topicPrefix = input.topicPrefix || '';
-    const rawResult = await ingestMemory({
+    const rawResult = await ingestMemoryInternal({
         content: topicPrefix ? `${topicPrefix}${conversationText}` : conversationText,
         scopes: input.scopes,
         source: input.source,
         eventDate: input.sessionDate,
-    });
+    }, options);
     const result = {
         rawId: rawResult.id,
         extractedMemories: [],
@@ -1202,7 +1638,7 @@ async function ingestConversation(input) {
     const batchSavedIds = [];
     for (const unit of units) {
         try {
-            const saved = await saveMemory({
+            const saved = await saveMemoryInternal({
                 topic: topicPrefix ? `${topicPrefix}${unit.topic}` : unit.topic,
                 kind: unit.kind,
                 summary: unit.summary,
@@ -1212,7 +1648,7 @@ async function ingestConversation(input) {
                 source: input.source,
                 excludeIds: batchSavedIds,
                 eventDate: input.sessionDate,
-            });
+            }, (0, provenance_js_1.appendProvenanceSourceRefs)(options, [`raw_memory:${rawResult.id}`]));
             const now = Date.now();
             adapter
                 .prepare(`INSERT OR REPLACE INTO decision_edges (from_id, to_id, relationship, reason, weight, created_at)
@@ -1231,4 +1667,10 @@ async function ingestConversation(input) {
     }
     return result;
 }
+async function ingestConversation(input) {
+    return ingestConversationInternal((0, provenance_js_1.sanitizePublicIngestConversationInput)(input));
+}
+async function ingestConversationWithTrustedProvenance(input, options) {
+    return ingestConversationInternal((0, provenance_js_1.sanitizePublicIngestConversationInput)(input), options);
+}
 //# sourceMappingURL=api.js.map