@indexnetwork/protocol 3.0.0 → 3.1.0-rc.247.1

package/dist/opportunity/opportunity.graph.js

@@ -28,6 +28,7 @@ import { protocolLogger, withCallLogging } from '../shared/observability/protoco
 import { timed } from '../shared/observability/performance.js';
 import { renderNetworkContext } from '../shared/network/metadata.renderer.js';
 import { requestContext } from "../shared/observability/request-context.js";
+import { mergeOpportunityEvidence, withCandidateEvidence, withMatchedStrategies, } from './opportunity.evidence.js';
 const logger = protocolLogger('OpportunityGraph');
 /** Time window for persist-node dedup. Parallel jobs arrive within seconds; 10 min catches those while allowing new opportunities for long-connected pairs. */
 const DEDUP_WINDOW_MS = 10 * 60 * 1000;
@@ -43,6 +44,13 @@ function getSourcePremiseDiscoveryLimit() {
     const parsed = Number.parseInt(raw, 10);
     return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_SOURCE_PREMISE_DISCOVERY_LIMIT;
 }
+function buildEvaluatorEvidenceKey(candidate) {
+    return [
+        candidate.candidateUserId,
+        candidate.networkId,
+        candidate.candidateIntentId ?? candidate.candidatePremiseId ?? candidate.sourceContextId ?? 'profile',
+    ].join(':');
+}
 /**
  * Builds a compact text summary of the discoverer's profile and active intents
  * for use as profileContext in HyDE generation.
@@ -210,7 +218,7 @@ export class OpportunityGraphFactory {
             // BACKEND-5: thousands of parallel vector searches for premise-rich users.
             const sourcePremises = [];
             const contextToIntentEnabled = process.env.DISCOVERY_CONTEXT_TO_INTENT !== '0';
-            const rawContexts = contextToIntentEnabled
+            const rawContexts = contextToIntentEnabled && typeof this.database.getUserContexts === 'function'
                 ? await this.database.getUserContexts(discoveryUserId)
                 : [];
             const sourceContexts = rawContexts
@@ -573,7 +581,7 @@ export class OpportunityGraphFactory {
                                 const intentNetworkIds = await this.database.getNetworkIdsForIntent(intent.id);
                                 const overlapping = sharedIndexIds.filter(id => intentNetworkIds.includes(id));
                                 for (const networkId of overlapping) {
-                                    directCandidates.push({
+                                    directCandidates.push(withCandidateEvidence({
                                         candidateUserId: state.targetUserId,
                                         candidateIntentId: intent.id,
                                         networkId,
@@ -582,22 +590,21 @@ export class OpportunityGraphFactory {
                                         candidatePayload: intent.payload,
                                         candidateSummary: intent.summary ?? undefined,
                                         discoverySource: 'query',
-                                    });
+                                    }));
                                 }
                             }
                         }
                         // Always add a profile-level candidate (so evaluation runs even without intents)
                         if (directCandidates.length === 0) {
-                            directCandidates.push({
+                            directCandidates.push(withCandidateEvidence({
                                 candidateUserId: state.targetUserId,
-                                candidateIntentId: undefined,
                                 networkId: sharedIndexIds[0],
                                 similarity: 1.0,
                                 lens: 'explicit_mention',
                                 candidatePayload: '',
                                 candidateSummary: undefined,
                                 discoverySource: 'query',
-                            });
+                            }));
                         }
                         logger.verbose('[Graph:Discovery] Direct candidates constructed', {
                             count: directCandidates.length,
@@ -766,7 +773,7 @@ export class OpportunityGraphFactory {
                                 minScore,
                             });
                             for (const r of results.filter((x) => x.type === 'intent')) {
-                                all.push({
+                                all.push(withCandidateEvidence({
                                     candidateUserId: r.userId,
                                     candidateIntentId: r.id,
                                     networkId: targetIndex.networkId,
@@ -775,10 +782,10 @@ export class OpportunityGraphFactory {
                                     candidatePayload: '',
                                     candidateSummary: undefined,
                                     discoverySource: 'query',
-                                });
+                                }));
                             }
                             for (const r of results.filter((x) => x.type === 'premise')) {
-                                all.push({
+                                all.push(withCandidateEvidence({
                                     candidateUserId: r.userId,
                                     candidatePremiseId: r.id,
                                     networkId: targetIndex.networkId,
@@ -787,7 +794,7 @@ export class OpportunityGraphFactory {
                                     candidatePayload: '',
                                     candidateSummary: undefined,
                                     discoverySource: 'query',
-                                });
+                                }));
                             }
                         }));
                         const intentCount = all.filter((c) => c.candidateIntentId).length;
@@ -847,23 +854,27 @@ export class OpportunityGraphFactory {
                                 excludeUserId: discoveryUserId,
                                 limitPerSource: PREMISE_MATCH_LIMIT_PER_SOURCE,
                             })
-                            : (await Promise.all(sourcePremises.map(sp => self.database.searchPremisesBySimilarity({
-                                embedding: sp.embedding,
-                                networkIds: targetNetworkIds,
-                                excludeUserId: discoveryUserId,
-                                limit: PREMISE_MATCH_LIMIT_PER_SOURCE,
-                            })))).flat();
+                            : (await Promise.all(sourcePremises.map(async (sp) => {
+                                const results = await self.database.searchPremisesBySimilarity({
+                                    embedding: sp.embedding,
+                                    networkIds: targetNetworkIds,
+                                    excludeUserId: discoveryUserId,
+                                    limit: PREMISE_MATCH_LIMIT_PER_SOURCE,
+                                });
+                                return results.map((r) => ({ ...r, sourcePremiseId: sp.premiseId }));
+                            }))).flat();
                         const premiseCandidates = [];
                         for (const r of rawResults) {
-                            premiseCandidates.push({
+                            premiseCandidates.push(withCandidateEvidence({
                                 candidateUserId: r.userId,
+                                sourcePremiseId: r.sourcePremiseId,
                                 candidatePremiseId: r.premiseId,
                                 networkId: r.networkId,
                                 similarity: typeof r.similarity === 'number' ? r.similarity : parseFloat(String(r.similarity)),
                                 lens: 'premise_match',
                                 candidatePayload: r.assertionText ?? '',
                                 discoverySource: 'premise-similarity',
-                            });
+                            }));
                         }
                         // Dedup by userId + premiseId + networkId (a premise can appear in multiple networks)
                         const byKey = new Map();
@@ -921,16 +932,17 @@ export class OpportunityGraphFactory {
                                     minScore,
                                 });
                                 for (const r of results.filter(r => r.type === 'intent')) {
-                                    contextCandidates.push({
+                                    contextCandidates.push(withCandidateEvidence({
                                         candidateUserId: r.userId,
                                         candidateIntentId: r.id,
+                                        sourceContextId: ctx.contextId,
                                         networkId: ctx.networkId,
                                         similarity: r.score,
                                         lens: r.matchedVia,
                                         candidatePayload: '',
                                         candidateSummary: undefined,
                                         discoverySource: 'context-to-intent',
-                                    });
+                                    }));
                                 }
                             }
                             else {
@@ -943,16 +955,17 @@ export class OpportunityGraphFactory {
                                     minScore: minScore,
                                 });
                                 for (const r of results) {
-                                    contextCandidates.push({
+                                    contextCandidates.push(withCandidateEvidence({
                                         candidateUserId: r.userId,
                                         candidateIntentId: r.intentId,
+                                        sourceContextId: ctx.contextId,
                                         networkId: r.networkId,
                                         similarity: typeof r.similarity === 'number' ? r.similarity : parseFloat(String(r.similarity)),
                                         lens: 'context_match',
                                         candidatePayload: r.payload ?? '',
                                         candidateSummary: r.summary ?? undefined,
                                         discoverySource: 'context-to-intent',
-                                    });
+                                    }));
                                 }
                             }
                         }
@@ -988,18 +1001,24 @@ export class OpportunityGraphFactory {
                                 }
                                 else {
                                     existing._strategies.add(c.discoverySource ?? 'unknown');
+                                    const mergedEvidence = mergeOpportunityEvidence(existing.evidence, c.evidence);
                                     if (c.similarity > existing.similarity) {
-                                        Object.assign(existing, c);
+                                        Object.assign(existing, { ...c, evidence: mergedEvidence });
+                                    }
+                                    else {
+                                        existing.evidence = mergedEvidence;
                                     }
                                 }
                             }
                         }
                         return Array.from(merged.values()).map(({ _strategies, ...c }) => {
+                            const matchedStrategies = Array.from(_strategies);
                             const boost = Math.min((_strategies.size - 1) * 0.05, 0.15);
                             return {
                                 ...c,
                                 similarity: Math.min(c.similarity + boost, 1.0),
-                                matchedStrategies: Array.from(_strategies),
+                                matchedStrategies,
+                                evidence: withMatchedStrategies(mergeOpportunityEvidence(c.evidence), matchedStrategies),
                             };
                         });
                     }
@@ -1068,7 +1087,7 @@ export class OpportunityGraphFactory {
                             minScore,
                         });
                         for (const result of results.filter((r) => r.type === 'intent')) {
-                            allCandidates.push({
+                            allCandidates.push(withCandidateEvidence({
                                 candidateUserId: result.userId,
                                 candidateIntentId: result.id,
                                 networkId: targetIndex.networkId,
@@ -1077,10 +1096,10 @@ export class OpportunityGraphFactory {
                                 candidatePayload: '',
                                 candidateSummary: undefined,
                                 discoverySource: 'query',
-                            });
+                            }));
                         }
                         for (const result of results.filter((r) => r.type === 'premise')) {
-                            allCandidates.push({
+                            allCandidates.push(withCandidateEvidence({
                                 candidateUserId: result.userId,
                                 candidatePremiseId: result.id,
                                 networkId: targetIndex.networkId,
@@ -1089,7 +1108,7 @@ export class OpportunityGraphFactory {
                                 candidatePayload: '',
                                 candidateSummary: undefined,
                                 discoverySource: 'query',
-                            });
+                            }));
                         }
                     }));
                     const byUserAndIndex = new Map();
@@ -1299,6 +1318,7 @@ export class OpportunityGraphFactory {
                             summary: i.summary,
                         })),
                         networkId: '', // Placeholder — overwritten per-pairing below
+                        evidenceKey: `${discoveryUserId}::source`,
                         ragScore: undefined,
                         matchedVia: undefined,
                     };
@@ -1313,6 +1333,7 @@ export class OpportunityGraphFactory {
                                 intentSummary = intent.summary ?? undefined;
                             }
                         }
+                        const evidenceKey = buildEvaluatorEvidenceKey(c);
                         return {
                             userId: c.candidateUserId,
                             profile: {
@@ -1327,14 +1348,35 @@ export class OpportunityGraphFactory {
                                 ? [{ intentId: c.candidateIntentId, payload: intentPayload ?? '', summary: intentSummary }]
                                 : undefined,
                             networkId: c.networkId,
+                            evidenceKey,
                             ragScore: c.similarity * 100,
                             matchedVia: c.lens,
+                            evidence: c.evidence,
                         };
                     }));
                     const userIdToIndexId = new Map();
+                    const evidenceByEntityKey = new Map();
+                    const entityKeysByUserId = new Map();
                     for (const e of candidateEntities) {
                         if (!userIdToIndexId.has(e.userId))
                             userIdToIndexId.set(e.userId, e.networkId);
+                        if (e.evidenceKey) {
+                            evidenceByEntityKey.set(e.evidenceKey, mergeOpportunityEvidence(evidenceByEntityKey.get(e.evidenceKey), e.evidence));
+                            entityKeysByUserId.set(e.userId, [...(entityKeysByUserId.get(e.userId) ?? []), e.evidenceKey]);
+                        }
+                    }
+                    function evidenceForActor(actor) {
+                        if (actor.evidenceKey)
+                            return evidenceByEntityKey.get(actor.evidenceKey);
+                        const keys = entityKeysByUserId.get(actor.userId) ?? [];
+                        const intentKey = actor.intentId ? keys.find((key) => key.endsWith(`:${actor.intentId}`)) : undefined;
+                        if (intentKey)
+                            return evidenceByEntityKey.get(intentKey);
+                        // Avoid leaking unrelated resource evidence when the evaluator collapsed multiple
+                        // candidates for the same user into a profile-only actor.
+                        if (keys.length === 1)
+                            return evidenceByEntityKey.get(keys[0]);
+                        return undefined;
                     }
                     // Lower default threshold to 50 for better recall
                     const minScore = state.options.minScore ?? 50;
@@ -1495,6 +1537,7 @@ export class OpportunityGraphFactory {
                     const evaluatedOpportunities = pairwiseOpportunities.map((op) => ({
                         reasoning: op.reasoning,
                         score: op.score,
+                        evidence: mergeOpportunityEvidence(...op.actors.map(evidenceForActor)),
                         actors: op.actors.map((a) => {
                             const isSource = a.userId === discoveryUserId;
                             if (isSource) {
@@ -2682,6 +2725,9 @@ export class OpportunityGraphFactory {
                                 },
                                 confidence: String(evaluated.score / 100),
                                 status: initialStatus,
+                                metadata: {
+                                    evidence: evaluated.evidence ?? [],
+                                },
                             };
                         }
                         try {