@indexnetwork/protocol 6.12.1-rc.404.1 → 6.14.0-rc.406.1

package/dist/opportunity/application/opportunity.discovery-continuation-finalization.d.ts

@@ -0,0 +1,34 @@
+import type { Cache } from '../../shared/interfaces/cache.interface.js';
+import type { ChatGraphCompositeDatabase, Opportunity } from '../../shared/interfaces/database.interface.js';
+import type { CandidateMatch } from '../domain/opportunity.state.js';
+import type { DiscoverDebugStep, DiscoveryResultContract } from '../domain/opportunity.discovery.contracts.js';
+export interface DiscoveryContinuationCacheSession {
+    candidates: CandidateMatch[];
+}
+export interface DiscoveryContinuationGraphResult {
+    trace?: Array<{
+        node: string;
+        detail?: string;
+        data?: Record<string, unknown>;
+    }>;
+    error?: string;
+    remainingCandidates?: CandidateMatch[];
+    opportunities?: Opportunity[];
+}
+interface DiscoveryContinuationFinalizationInput<TOpportunity> {
+    result: DiscoveryContinuationGraphResult;
+    cache: Pick<Cache, 'set' | 'delete'>;
+    cacheKey: string;
+    cached: DiscoveryContinuationCacheSession;
+    userId: string;
+    discoveryId: string;
+    database: Pick<ChatGraphCompositeDatabase, 'getOpportunitiesByIds'>;
+    enrich: (opportunities: Opportunity[], debugSteps: DiscoverDebugStep[]) => Promise<TOpportunity[]>;
+}
+/**
+ * Finalizes a successful continuation graph result without owning session
+ * lookup, scope admission, or graph invocation. Cache failures are advisory;
+ * lifecycle refresh and presentation use the graph result regardless.
+ */
+export declare function finalizeDiscoveryContinuation<TOpportunity>(args: DiscoveryContinuationFinalizationInput<TOpportunity>): Promise<DiscoveryResultContract<TOpportunity>>;
+export {};

package/dist/opportunity/application/opportunity.discovery-continuation-finalization.js

@@ -0,0 +1,74 @@
+import { protocolLogger } from '../../shared/observability/protocol.logger.js';
+const logger = protocolLogger('OpportunityDiscover');
+/**
+ * Finalizes a successful continuation graph result without owning session
+ * lookup, scope admission, or graph invocation. Cache failures are advisory;
+ * lifecycle refresh and presentation use the graph result regardless.
+ */
+export async function finalizeDiscoveryContinuation(args) {
+    const debugSteps = [];
+    for (const trace of args.result.trace || []) {
+        debugSteps.push({
+            step: trace.node,
+            detail: trace.detail,
+            ...(trace.data ? { data: trace.data } : {}),
+        });
+    }
+    if (args.result.error) {
+        logger.warn('continueDiscovery graph returned error', { error: args.result.error });
+        return {
+            found: false,
+            count: 0,
+            message: 'Discovery continuation failed. Please start a new search.',
+            debugSteps,
+        };
+    }
+    const remaining = args.result.remainingCandidates || [];
+    let pagination;
+    try {
+        if (remaining.length > 0) {
+            await args.cache.set(args.cacheKey, {
+                ...args.cached,
+                candidates: remaining,
+            }, { ttl: 1800 });
+            pagination = {
+                discoveryId: args.discoveryId,
+                evaluated: args.cached.candidates.length - remaining.length,
+                remaining: remaining.length,
+            };
+        }
+        else {
+            await args.cache.delete(args.cacheKey);
+        }
+    }
+    catch (cacheErr) {
+        logger.warn('Failed to update discovery pagination cache', {
+            userId: args.userId,
+            discoveryId: args.discoveryId,
+            error: cacheErr instanceof Error ? cacheErr.message : String(cacheErr),
+        });
+    }
+    const opportunities = Array.isArray(args.result.opportunities) ? args.result.opportunities : [];
+    const refreshed = opportunities.length > 0
+        ? await args.database.getOpportunitiesByIds(opportunities.map((opportunity) => opportunity.id))
+        : [];
+    const refreshedById = new Map(refreshed.map((opportunity) => [opportunity.id, opportunity]));
+    const currentOpportunities = opportunities.map((opportunity) => refreshedById.get(opportunity.id) ?? opportunity);
+    if (currentOpportunities.length === 0) {
+        return {
+            found: false,
+            count: 0,
+            message: 'No more matching opportunities found in the remaining candidates.',
+            debugSteps,
+            pagination,
+        };
+    }
+    const enriched = await args.enrich(currentOpportunities, debugSteps);
+    return {
+        found: true,
+        count: enriched.length,
+        opportunities: enriched,
+        debugSteps,
+        pagination,
+    };
+}

package/dist/opportunity/application/opportunity.discovery-mcp-lifecycle-finalization.d.ts

@@ -0,0 +1,44 @@
+import type { OpportunityStatus } from '../../shared/interfaces/database.interface.js';
+import type { OpportunityCardLike } from './opportunity.card-presentation.js';
+import type { ExistingConnection, FormattedDiscoveryCandidate } from './opportunity.discover.js';
+type DiscoveryPagination = {
+    discoveryId: string;
+    evaluated: number;
+    remaining: number;
+};
+export interface DiscoveryMcpLifecycleFinalizationInput<TCard extends OpportunityCardLike> {
+    isMcp: boolean;
+    candidates: FormattedDiscoveryCandidate[];
+    existingConnections?: ExistingConnection[];
+    existingConnectionsForMention?: ExistingConnection[];
+    alreadyAcceptedPairs?: Array<{
+        opportunityId: string;
+        counterpartyUserId: string;
+    }>;
+    pagination?: DiscoveryPagination;
+    isIntroducerFlow: boolean;
+    displayLimit: number;
+    readOpportunitiesByIds: (ids: string[]) => Promise<Array<{
+        id: string;
+        status: OpportunityStatus;
+    }>>;
+    warn: (message: string, data: Record<string, unknown>) => void;
+    /** The caller supplies the only allowed safe-presentation path for card text. */
+    projectSafeCard: (candidate: FormattedDiscoveryCandidate) => TCard;
+}
+export interface DiscoveryMcpLifecycleFinalization<TCard extends OpportunityCardLike> {
+    displayedCards: TCard[];
+    /** Source candidates retain viewer approval data for facade-owned link minting. */
+    displayedCandidates: FormattedDiscoveryCandidate[];
+    negotiatingCount: number;
+    /** Adds lifecycle-aware completion copy after facade-owned link decoration. */
+    composeMessage: (baseMessage: string) => string;
+}
+/**
+ * Reconciles a discovery graph result with authoritative opportunity lifecycle
+ * rows before the MCP tool presents cards. Graph output is intentionally not
+ * trusted for new-card lifecycle after its negotiate phase. The tools facade
+ * continues to own link writes and the outer tool response.
+ */
+export declare function finalizeMcpDiscoveryLifecycle<TCard extends OpportunityCardLike>(input: DiscoveryMcpLifecycleFinalizationInput<TCard>): Promise<DiscoveryMcpLifecycleFinalization<TCard>>;
+export {};

package/dist/opportunity/application/opportunity.discovery-mcp-lifecycle-finalization.js

@@ -0,0 +1,92 @@
+function existingConnectionsNarrative(connections) {
+    if (connections.length === 0)
+        return '';
+    return ('\n\nYou already have a connection with: ' +
+        connections.map((connection) => connection.name + (connection.status ? ` (${connection.status})` : '')).join(', ') +
+        '. View on your home page.');
+}
+function alreadyAcceptedNarrative(alreadyAcceptedPairs) {
+    if (alreadyAcceptedPairs.length === 0)
+        return '';
+    return `\n\nYou already have ${alreadyAcceptedPairs.length} accepted opportunity(ies) with some of these candidates — open the existing chat with them rather than creating a new draft.`;
+}
+/**
+ * Reconciles a discovery graph result with authoritative opportunity lifecycle
+ * rows before the MCP tool presents cards. Graph output is intentionally not
+ * trusted for new-card lifecycle after its negotiate phase. The tools facade
+ * continues to own link writes and the outer tool response.
+ */
+export async function finalizeMcpDiscoveryLifecycle(input) {
+    const existingConnectionIds = new Set((input.existingConnections ?? [])
+        .map((connection) => connection.opportunityId)
+        .filter((id) => typeof id === 'string'));
+    let negotiatingCount = 0;
+    let visibleCandidates = input.candidates;
+    if (input.isMcp && input.candidates.length > 0) {
+        const newCardIds = input.candidates
+            .filter((candidate) => !existingConnectionIds.has(candidate.opportunityId))
+            .map((candidate) => candidate.opportunityId);
+        const refreshed = newCardIds.length > 0
+            ? await input.readOpportunitiesByIds(newCardIds)
+            : [];
+        const statusById = new Map(refreshed.map((opportunity) => [opportunity.id, opportunity.status]));
+        const draftCandidates = [];
+        for (const candidate of input.candidates) {
+            if (existingConnectionIds.has(candidate.opportunityId)) {
+                // Re-surfaced connections preserve their discover-time lifecycle.
+                draftCandidates.push(candidate);
+                continue;
+            }
+            const refreshedStatus = statusById.get(candidate.opportunityId);
+            if (refreshedStatus === 'draft') {
+                draftCandidates.push({ ...candidate, status: refreshedStatus });
+                continue;
+            }
+            if (refreshedStatus === 'negotiating') {
+                negotiatingCount += 1;
+                continue;
+            }
+            if (refreshedStatus === 'rejected' || refreshedStatus === 'stalled') {
+                continue;
+            }
+            // Pending, latent, and missing rows are not expected after the graph's
+            // negotiate phase. Preserve the established fail-closed display policy:
+            // do not surface a card, but make the deferred state observable.
+            input.warn('unexpected refreshed status — counting as negotiating', {
+                opportunityId: candidate.opportunityId,
+                refreshedStatus,
+            });
+            negotiatingCount += 1;
+        }
+        visibleCandidates = draftCandidates;
+    }
+    // Projection is supplied by the tools facade so this policy cannot choose a
+    // raw-reasoning path; callers must use getSafePresentationOrSkip-compatible copy.
+    const projectedCards = visibleCandidates.map(input.projectSafeCard);
+    const displayedCards = projectedCards.slice(0, input.displayLimit);
+    const displayedCandidates = visibleCandidates.slice(0, input.displayLimit);
+    const extraFromCap = projectedCards.length - displayedCards.length;
+    const existingNarrative = existingConnectionsNarrative(input.existingConnectionsForMention ?? input.existingConnections ?? []);
+    const acceptedNarrative = alreadyAcceptedNarrative(input.alreadyAcceptedPairs ?? []);
+    const totalRemaining = (input.pagination?.remaining ?? 0) + extraFromCap;
+    const completionNarrative = totalRemaining > 0 && input.pagination?.discoveryId
+        ? `\n\nThere are ${totalRemaining} more candidates. Ask if the user wants to see more — they can say "show me more" and you should call discover_opportunities with continueFrom="${input.pagination.discoveryId}".`
+        : input.isIntroducerFlow
+            ? '\n\nThese are all the introduction candidates I found for this person.'
+            : '\n\nThese are all the connections I found. If the user wants to attract more connections, suggest they create a signal — e.g. "Would you like to create a signal so others looking for someone like you can find you?" If they agree, call create_intent with a description based on what they were searching for.';
+    return {
+        displayedCards,
+        displayedCandidates,
+        negotiatingCount,
+        composeMessage(baseMessage) {
+            const message = baseMessage + existingNarrative + acceptedNarrative + completionNarrative;
+            if (!input.isMcp || negotiatingCount === 0)
+                return message;
+            if (displayedCards.length > 0) {
+                return message + `\n\n${negotiatingCount} more opportunit${negotiatingCount === 1 ? 'y is' : 'ies are'} still being evaluated — check back via \`list_opportunities\` shortly.`;
+            }
+            // Preserve existing/accepted facts but omit card-only completion copy.
+            return `Found candidates, but they're still being evaluated. Try \`list_opportunities\` in a minute — ${negotiatingCount} pending.` + existingNarrative + acceptedNarrative;
+        },
+    };
+}

package/dist/opportunity/application/opportunity.discovery-negotiation-summary.d.ts

@@ -0,0 +1,14 @@
+import type { NegotiationSummaryReader } from '../../shared/interfaces/negotiation-summary.interface.js';
+import type { DiscoveryNegotiationDigest } from '../../shared/schemas/negotiation-digest.schema.js';
+import type { DiscoveryNegotiation } from '../../shared/schemas/discovery-question.schema.js';
+export interface DiscoveryNegotiationSummaryInput {
+    negotiations: DiscoveryNegotiation[];
+    summarizer: NegotiationSummaryReader | undefined;
+    callerSignal?: AbortSignal;
+}
+/**
+ * Summarizes each already-admitted discovery negotiation independently. A
+ * missing, null, empty, or failed model response falls back per negotiation so
+ * one failure cannot suppress an ordered batch of deterministic digests.
+ */
+export declare function summarizeDiscoveryNegotiations(args: DiscoveryNegotiationSummaryInput): Promise<DiscoveryNegotiationDigest[]>;

package/dist/opportunity/application/opportunity.discovery-negotiation-summary.js

@@ -0,0 +1,46 @@
+import { buildFallbackDigest } from '../../capabilities/negotiation.summary.facade.js';
+import { protocolLogger } from '../../shared/observability/protocol.logger.js';
+import { traceAgent } from '../../shared/observability/trace.js';
+const logger = protocolLogger('OpportunityDiscoveryNegotiationSummary');
+const NEGOTIATION_SUMMARY_TIMEOUT_MS_DEFAULT = 5000;
+function parsePositiveIntEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0 || n > Number.MAX_SAFE_INTEGER)
+        return fallback;
+    return n;
+}
+function combineWithDeadline(callerSignal, deadlineMs) {
+    const deadline = AbortSignal.timeout(deadlineMs);
+    if (!callerSignal)
+        return deadline;
+    return AbortSignal.any([callerSignal, deadline]);
+}
+/**
+ * Summarizes each already-admitted discovery negotiation independently. A
+ * missing, null, empty, or failed model response falls back per negotiation so
+ * one failure cannot suppress an ordered batch of deterministic digests.
+ */
+export async function summarizeDiscoveryNegotiations(args) {
+    const perNegTimeoutMs = parsePositiveIntEnv('NEGOTIATION_SUMMARY_TIMEOUT_MS', NEGOTIATION_SUMMARY_TIMEOUT_MS_DEFAULT);
+    return traceAgent(`Negotiation summary (${args.negotiations.length})`, () => Promise.all(args.negotiations.map(async (negotiation) => {
+        if (!args.summarizer)
+            return buildFallbackDigest(negotiation);
+        const signal = combineWithDeadline(args.callerSignal, perNegTimeoutMs);
+        try {
+            const digest = await args.summarizer.summarize(negotiation, { signal });
+            return digest ?? buildFallbackDigest(negotiation);
+        }
+        catch (err) {
+            const aborted = err instanceof Error && err.name === 'AbortError';
+            logger.warn('negotiationSummary.summarize threw — using fallback digest', {
+                counterpartyHint: negotiation.counterpartyHint,
+                aborted,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return buildFallbackDigest(negotiation);
+        }
+    })), (digests) => `${digests.length} digest${digests.length === 1 ? '' : 's'}`);
+}

package/dist/opportunity/application/opportunity.enricher.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Opportunity enricher: when creating an opportunity, find overlapping existing
+ * opportunities (by non-introducer actor userId), check semantic relatedness, and
+ * optionally merge into a single enriched opportunity and expire the old one(s).
+ */
+import type { CreateOpportunityData, Opportunity, OpportunityStatus } from '../../shared/interfaces/database.interface.js';
+import type { Embedder } from '../../shared/interfaces/embedder.interface.js';
+/**
+ * Statuses excluded from the merge-candidate pool by default.
+ *
+ * - 'accepted': the pair already connected — do NOT fold a new discovery into
+ *   the historical opp. IND-237 surfaces the existing conversation separately.
+ * - 'negotiating': a negotiation is in-flight for this pair; rolling a new
+ *   candidate into it would blur the outcome of the active turn. Wait for the
+ *   negotiation to finalize (→ draft/pending/rejected/stalled) first, then
+ *   enrichment can pick it up on the next pass.
+ * - 'expired': already superseded by a later enriched opportunity. Without this
+ *   exclusion, each enrichment cycle re-merges previously-expired enriched
+ *   opportunities, compounding their actor arrays into 100+ entries.
+ *
+ * Exported for callers that want to extend rather than replace the default.
+ */
+export declare const DEFAULT_ENRICHER_EXCLUDE_STATUSES: OpportunityStatus[];
+export type EnricherDatabase = {
+    findOpportunitiesByActors(actorIds: string[], options?: {
+        includeIntroducers?: boolean;
+        statuses?: OpportunityStatus[];
+        excludeStatuses?: OpportunityStatus[];
+    }): Promise<Opportunity[]>;
+};
+export type EnrichmentResult = {
+    enriched: false;
+    data: CreateOpportunityData;
+} | {
+    enriched: true;
+    data: CreateOpportunityData;
+    expiredIds: string[];
+    resolvedStatus: OpportunityStatus;
+};
+export type EnrichOrCreateOptions = {
+    similarityThreshold?: number;
+    /**
+     * Statuses to exclude from the merge-candidate pool. Defaults to
+     * {@link DEFAULT_ENRICHER_EXCLUDE_STATUSES} (`['accepted', 'negotiating']`).
+     * Pass an empty array `[]` to consider all statuses.
+     */
+    excludeStatuses?: OpportunityStatus[];
+    /** Restrict merge/expiration candidates to the authoritative owned intent. */
+    ownedIntentScope?: {
+        triggerIntentId: string;
+        ownerUserId: string;
+    };
+};
+/**
+ * Enrich or create: find overlapping opportunities, filter by semantic relatedness
+ * using a two-phase approach, merge actors and interpretation into a single
+ * CreateOpportunityData, and return the data plus IDs to expire. If no related
+ * overlap, return original data unchanged.
+ *
+ * Phase 1 — Intent check (free, no API call):
+ *   Shared intent IDs mean the same declared user goal drove both opportunities.
+ *   This is rare because the IntentReconciler already deduplicates intents per-user
+ *   upstream, but when it fires it is definitive.
+ *
+ * Phase 2 — Batched embedding similarity (one API call for all remaining):
+ *   For opportunities without shared intents, embed all reasoning texts in a single
+ *   batch call and compare cosine similarity. Cross-user intent comparison (e.g.
+ *   Alice's "find ML co-founder" vs Bob's "join ML startup") is implicitly handled
+ *   here since reasoning text synthesizes both users' intents.
+ */
+export declare function enrichOrCreate(database: EnricherDatabase, embedder: Embedder, newData: CreateOpportunityData, options?: EnrichOrCreateOptions): Promise<EnrichmentResult>;

package/dist/opportunity/application/opportunity.enricher.js

@@ -0,0 +1,280 @@
+/**
+ * Opportunity enricher: when creating an opportunity, find overlapping existing
+ * opportunities (by non-introducer actor userId), check semantic relatedness, and
+ * optionally merge into a single enriched opportunity and expire the old one(s).
+ */
+import { getAbortSignalConfig } from '../../shared/agent/model-signal.js';
+import { protocolLogger } from '../../shared/observability/protocol.logger.js';
+const logger = protocolLogger('OpportunityEnricher');
+const DEFAULT_SIMILARITY_THRESHOLD = 0.7;
+const MIN_REASONING_LENGTH_FOR_EMBEDDING = 10;
+/**
+ * Statuses excluded from the merge-candidate pool by default.
+ *
+ * - 'accepted': the pair already connected — do NOT fold a new discovery into
+ *   the historical opp. IND-237 surfaces the existing conversation separately.
+ * - 'negotiating': a negotiation is in-flight for this pair; rolling a new
+ *   candidate into it would blur the outcome of the active turn. Wait for the
+ *   negotiation to finalize (→ draft/pending/rejected/stalled) first, then
+ *   enrichment can pick it up on the next pass.
+ * - 'expired': already superseded by a later enriched opportunity. Without this
+ *   exclusion, each enrichment cycle re-merges previously-expired enriched
+ *   opportunities, compounding their actor arrays into 100+ entries.
+ *
+ * Exported for callers that want to extend rather than replace the default.
+ */
+export const DEFAULT_ENRICHER_EXCLUDE_STATUSES = ['accepted', 'negotiating', 'expired'];
+/**
+ * Cosine similarity between two vectors (0–1).
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom === 0)
+        return 0;
+    const sim = dot / denom;
+    return Math.max(0, Math.min(1, sim));
+}
+/**
+ * Resolve enriched opportunity status from related opportunities' statuses and the incoming status.
+ * Priority: accepted > pending > rejected > stalled > draft (only when incoming is draft) > latent.
+ * The incoming status is included so we do not wrongly downgrade when the new opportunity has a higher-priority status.
+ * When incoming is 'draft' (e.g. from in-chat discovery), we preserve draft so the opportunity stays chat-only and
+ * does not appear on the home view (home excludes draft).
+ * When incoming is NOT draft (e.g. 'latent' from the background broker), existing draft status does NOT contaminate
+ * the result — the broker-created opportunity retains its own status and can appear on the home view.
+ */
+function resolveEnrichedStatus(relatedStatuses, incomingStatus) {
+    const statuses = incomingStatus ? [...relatedStatuses, incomingStatus] : relatedStatuses;
+    if (statuses.includes('accepted'))
+        return 'accepted';
+    if (statuses.includes('pending'))
+        return 'pending';
+    if (statuses.includes('rejected'))
+        return 'rejected';
+    if (statuses.includes('stalled'))
+        return 'stalled';
+    if (incomingStatus === 'draft')
+        return 'draft';
+    return 'latent';
+}
+/**
+ * Extract non-introducer actor userIds from create data.
+ */
+function getNonIntroducerUserIds(data) {
+    const ids = data.actors
+        .filter((a) => a.role !== 'introducer')
+        .map((a) => a.userId);
+    return [...new Set(ids)];
+}
+/**
+ * Extract intent IDs from actors.
+ */
+function belongsToOwnedIntent(opportunity, scope) {
+    if (opportunity.detection.triggeredBy === scope.triggerIntentId)
+        return true;
+    return opportunity.actors.some((actor) => actor.userId === scope.ownerUserId && actor.intent === scope.triggerIntentId);
+}
+function getIntentIdsFromActors(actors) {
+    const ids = new Set();
+    for (const a of actors) {
+        if (a.intent)
+            ids.add(a.intent);
+    }
+    return ids;
+}
+/**
+ * Check if two opportunities share at least one intent ID.
+ */
+function shareIntentIds(newData, existing) {
+    const newIntents = getIntentIdsFromActors(newData.actors);
+    const existingIntents = getIntentIdsFromActors(existing.actors);
+    for (const id of newIntents) {
+        if (existingIntents.has(id))
+            return true;
+    }
+    return false;
+}
+/**
+ * Merge actors from new data and existing opportunities: union by (networkId, userId, intent),
+ * preserving all unique introducers and preferring newer role on conflict.
+ */
+function mergeActors(newData, existingList) {
+    const key = (a) => `${a.networkId}:${a.userId}:${a.intent ?? ''}`;
+    const map = new Map();
+    // Add all from existing first (older)
+    for (const opp of existingList) {
+        for (const a of opp.actors) {
+            map.set(key(a), a);
+        }
+    }
+    // Add/overwrite with new (newer wins for same key, e.g. role)
+    for (const a of newData.actors) {
+        map.set(key(a), a);
+    }
+    return [...map.values()];
+}
+/**
+ * Merge interpretation: single reasoning (new data only), max confidence, merged signals.
+ * We use only the new opportunity's reasoning to avoid repetitive concatenation when
+ * multiple overlapping opportunities share the same or similar text (e.g. same pair
+ * across indexes), which previously produced long duplicated paragraphs in chat cards.
+ */
+function mergeInterpretation(newData, existingList) {
+    const reasoning = newData.interpretation.reasoning;
+    let maxConf = typeof newData.interpretation.confidence === 'number'
+        ? newData.interpretation.confidence
+        : parseFloat(String(newData.interpretation.confidence ?? 0));
+    for (const o of existingList) {
+        const c = o.interpretation?.confidence;
+        const cNum = typeof c === 'number' ? c : parseFloat(String(c ?? 0));
+        if (cNum > maxConf)
+            maxConf = cNum;
+    }
+    const confidence = maxConf;
+    const signals = [
+        ...(newData.interpretation.signals ?? []),
+        ...existingList.flatMap((o) => o.interpretation?.signals ?? []),
+    ];
+    const seen = new Set();
+    const dedupedSignals = signals.filter((s) => {
+        const k = `${s.type}:${s.detail ?? ''}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+    return {
+        category: newData.interpretation.category,
+        reasoning,
+        confidence: typeof confidence === 'string' ? parseFloat(confidence) : confidence,
+        signals: dedupedSignals.length > 0 ? dedupedSignals : newData.interpretation.signals,
+    };
+}
+/**
+ * Enrich or create: find overlapping opportunities, filter by semantic relatedness
+ * using a two-phase approach, merge actors and interpretation into a single
+ * CreateOpportunityData, and return the data plus IDs to expire. If no related
+ * overlap, return original data unchanged.
+ *
+ * Phase 1 — Intent check (free, no API call):
+ *   Shared intent IDs mean the same declared user goal drove both opportunities.
+ *   This is rare because the IntentReconciler already deduplicates intents per-user
+ *   upstream, but when it fires it is definitive.
+ *
+ * Phase 2 — Batched embedding similarity (one API call for all remaining):
+ *   For opportunities without shared intents, embed all reasoning texts in a single
+ *   batch call and compare cosine similarity. Cross-user intent comparison (e.g.
+ *   Alice's "find ML co-founder" vs Bob's "join ML startup") is implicitly handled
+ *   here since reasoning text synthesizes both users' intents.
+ */
+export async function enrichOrCreate(database, embedder, newData, options) {
+    const actorUserIds = getNonIntroducerUserIds(newData);
+    if (actorUserIds.length === 0) {
+        return { enriched: false, data: newData };
+    }
+    const excludeStatuses = options?.excludeStatuses ?? DEFAULT_ENRICHER_EXCLUDE_STATUSES;
+    const pairOverlaps = await database.findOpportunitiesByActors(actorUserIds, { excludeStatuses });
+    const ownedIntentScope = options?.ownedIntentScope;
+    const overlapping = ownedIntentScope
+        ? pairOverlaps.filter((opportunity) => belongsToOwnedIntent(opportunity, ownedIntentScope))
+        : pairOverlaps;
+    if (ownedIntentScope && pairOverlaps.length > overlapping.length) {
+        logger.info('Excluded cross-trigger overlaps from owned-intent enrichment', {
+            triggerIntentId: ownedIntentScope.triggerIntentId,
+            pairOverlapCount: pairOverlaps.length,
+            sameTriggerOverlapCount: overlapping.length,
+        });
+    }
+    if (overlapping.length === 0) {
+        return { enriched: false, data: newData };
+    }
+    const threshold = options?.similarityThreshold ?? DEFAULT_SIMILARITY_THRESHOLD;
+    // Phase 1: Intent-based relatedness (free, strongest signal)
+    const related = [];
+    const remaining = [];
+    for (const opp of overlapping) {
+        if (shareIntentIds(newData, opp)) {
+            related.push(opp);
+        }
+        else {
+            remaining.push(opp);
+        }
+    }
+    // Phase 2: Batched embedding similarity (one API call for all remaining)
+    if (remaining.length > 0) {
+        const newReasoning = (newData.interpretation?.reasoning ?? '').trim();
+        // Only embed opps where both reasonings are long enough
+        const embeddable = [];
+        for (const opp of remaining) {
+            const existingReasoning = (opp.interpretation?.reasoning ?? '').trim();
+            if (newReasoning.length >= MIN_REASONING_LENGTH_FOR_EMBEDDING &&
+                existingReasoning.length >= MIN_REASONING_LENGTH_FOR_EMBEDDING) {
+                embeddable.push(opp);
+            }
+            // Short reasoning + no shared intents (Phase 1 missed) → not related
+        }
+        if (embeddable.length > 0) {
+            try {
+                const textsToEmbed = [
+                    newReasoning,
+                    ...embeddable.map((o) => (o.interpretation?.reasoning ?? '').trim()),
+                ];
+                const vectors = (await embedder.generate(textsToEmbed, undefined, getAbortSignalConfig()));
+                const newVec = vectors[0];
+                if (newVec?.length) {
+                    for (let i = 0; i < embeddable.length; i++) {
+                        const existingVec = vectors[i + 1];
+                        if (existingVec?.length && cosineSimilarity(newVec, existingVec) >= threshold) {
+                            related.push(embeddable[i]);
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                logger.warn('Embedding check failed; intent-matched opportunities already captured', { error: e });
+                // Phase 1 matches are preserved; remaining opps without shared intents are not related
+            }
+        }
+    }
+    if (related.length === 0) {
+        return { enriched: false, data: newData };
+    }
+    const mergedActors = mergeActors(newData, related);
+    const mergedInterpretation = mergeInterpretation(newData, related);
+    const enrichedFrom = related.map((o) => o.id);
+    const mergedConfidence = typeof mergedInterpretation.confidence === 'number'
+        ? String(mergedInterpretation.confidence)
+        : mergedInterpretation.confidence;
+    const enrichedData = {
+        ...newData,
+        detection: {
+            ...newData.detection,
+            source: 'enrichment',
+            enrichedFrom,
+        },
+        actors: mergedActors,
+        interpretation: mergedInterpretation,
+        confidence: mergedConfidence,
+    };
+    const resolvedStatus = resolveEnrichedStatus(related.map((o) => o.status), newData.status);
+    logger.verbose('Enriched opportunity', {
+        enrichedFrom,
+        actorCount: mergedActors.length,
+    });
+    return {
+        enriched: true,
+        data: enrichedData,
+        expiredIds: enrichedFrom,
+        resolvedStatus,
+    };
+}