@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0

package/dist/opportunities/opportunity.graph.shared.d.ts

@@ -1,173 +0,0 @@
-/**
- * Shared vocabulary for the opportunity graph's nodes and modes.
- *
- * The nodes used to be closures inside `OpportunityGraphFactory.createGraph()`,
- * capturing `this` and the resolved thresholds. They are now top-level functions
- * that take an explicit {@link OpportunityGraphDeps} bag, so each node is
- * readable — and testable — on its own. This module owns the pieces more than
- * one of them needs: the dependency bag, the loggers, the trace wrapper, and the
- * small pure helpers.
- */
-import type { Id } from '../shared/interfaces/database.interface.js';
-import { OpportunityGraphState, type IndexedIntent, type SourceProfileData, type CandidateMatch } from './opportunity.state.js';
-import type { CandidateProfile, EvaluatorEntity, EvaluatorInput } from "./opportunity.evaluator.js";
-import type { OpportunityGraphDatabase, Opportunity } from '../shared/interfaces/database.interface.js';
-import type { Embedder } from '../shared/interfaces/embedder.interface.js';
-import type { NegotiationGraphLike } from '../negotiations/negotiation.module.js';
-import type { AgentDispatcher } from '../shared/interfaces/agent-dispatcher.interface.js';
-import type { QueueOpportunityNotificationFn } from "./opportunity.lifecycle.js";
-import type { StampNewbornOpportunitiesFn } from "./opportunity.newborn-stamping.js";
-/** The graph's channel state, as every node sees it. */
-export type OpportunityState = typeof OpportunityGraphState.State;
-/** Optional evaluator for testing (avoids LLM calls). */
-export type OpportunityEvaluatorLike = {
-    invoke?: (sourceProfileContext: string, candidates: CandidateProfile[], options: {
-        minScore?: number;
-    }) => Promise<Array<{
-        sourceId: string;
-        candidateId: string;
-        score: number;
-        reasoning: string;
-        valencyRole: 'Agent' | 'Patient' | 'Peer';
-    }>>;
-    invokeEntityBundle?: (input: EvaluatorInput, options: {
-        minScore?: number;
-        returnAll?: boolean;
-        signal?: AbortSignal;
-    }) => Promise<Array<{
-        reasoning: string;
-        score: number;
-        actors: Array<{
-            userId: string;
-            role: 'agent' | 'patient' | 'peer';
-            intentId?: string | null;
-            evidenceKey?: string | null;
-        }>;
-    }>>;
-};
-/** Input shape for the HyDE graph invoke call (query-based embedding). */
-export interface HydeGeneratorInvokeInput {
-    sourceType: 'query';
-    sourceText: string;
-    forceRegenerate?: boolean;
-    profileContext?: string;
-}
-/** The compiled HyDE graph, as the discovery node consumes it. */
-export interface OpportunityHydeGenerator {
-    invoke: (input: HydeGeneratorInvokeInput) => Promise<{
-        hydeEmbeddings: Record<string, number[]>;
-        lenses?: Array<{
-            label: string;
-            corpus: 'profiles' | 'intents' | 'premises';
-        }>;
-        hydeDocuments?: Record<string, {
-            hydeText?: string;
-            lens?: string;
-        }>;
-    }>;
-}
-export interface OpportunityGraphThresholdOverrides {
-    retrievalMinSimilarity?: number;
-    evaluatorMinScore?: number;
-}
-/**
- * Everything the nodes and modes reach for. Composed once by
- * `OpportunityGraphFactory` and passed to each function explicitly.
- */
-export interface OpportunityGraphDeps {
-    database: OpportunityGraphDatabase;
-    embedder: Embedder;
-    hydeGenerator: OpportunityHydeGenerator;
-    /** Resolved evaluator: the injected test double, or a real `OpportunityEvaluator`. */
-    evaluatorAgent: OpportunityEvaluatorLike;
-    queueNotification?: QueueOpportunityNotificationFn;
-    negotiationGraph?: NegotiationGraphLike;
-    /**
-     * Used on the chat path to decide whether to wait for the user's personal
-     * agent (long timeout) or fall back to the system agent immediately
-     * (short timeout). Without it, the chat path always uses a short timeout.
-     */
-    agentDispatcher?: Pick<AgentDispatcher, 'hasExternalAgent'>;
-    /**
-     * Callback to enqueue a negotiate_existing job for an opportunity.
-     * When provided, negotiate_existing mode uses this to queue follow-up
-     * negotiations after introducer approval.
-     */
-    queueNegotiateExisting?: (opportunityId: string, userId: string) => Promise<void>;
-    /** Host-side P4b stamper. Omitted by manual/introducer/enrichment roots. */
-    stampNewbornOpportunities?: StampNewbornOpportunitiesFn;
-    retrievalMinSimilarity: number;
-    evaluatorMinScore: number;
-}
-export declare const logger: import("../shared/observability/log.js").LoggerWithSource;
-export declare const prepLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const scopeLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const resolveLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const discoveryLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const evaluationLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const negotiateLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const rankingLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const introValidationLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const introEvaluationLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const persistLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const persistPathLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const persistDedupLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const readLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const updateLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const deleteLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const sendLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const negotiateExistingLog: import("../shared/observability/log.js").LoggerWithSource;
-export declare const routingLog: import("../shared/observability/log.js").LoggerWithSource;
-/**
- * Error text can include provider response bodies, URLs, and credentials. Keep
- * observability useful by retaining only a conservative error class at this
- * boundary; detailed errors are intentionally not emitted from graph traces.
- */
-export declare function safeOpportunityGraphError(_error: unknown): string;
-/**
- * Wraps a graph node function to emit agent_start/agent_end trace events
- * at its boundaries so the frontend TRACE panel shows real-time progress.
- * @param traceName - Kebab-case agent name (e.g. "opportunity-prep")
- * @param nodeFn - The original node function
- * @param summaryFn - Optional function to derive a summary string from the node result
- */
-export declare function withNodeTrace<S, R>(traceName: string, nodeFn: (state: S) => Promise<R>, summaryFn?: (result: R) => string | undefined): (state: S) => Promise<R>;
-/** Shared trace summary: surface `error` when a node returned one. */
-export declare function errorSummary(result: unknown): string | undefined;
-/** Time window for persist-node dedup. Suppresses a second opportunity with the same person while a recent one (within 30 days) is still in flight, so a person is not re-surfaced multiple times within a month (EDG-23). */
-export declare const DEDUP_WINDOW_MS: number;
-export declare function isActiveNegotiationTaskFresh(task: {
-    state: string;
-    updatedAt: Date;
-}): boolean;
-export declare function triggerForOwner(opportunity: Opportunity, ownerUserId: string): string | undefined;
-export declare function belongsToOwnedIntent(opportunity: Opportunity, ownerUserId: string, triggerIntentId: string): boolean;
-export declare function getRejectionCooldownMs(): number;
-/**
- * Similarity multiplier applied to candidates that fall within the rejection
- * cool-down window (IND-567). 0.5 halves their ranking score, typically
- * pushing them below the evaluation-batch cut while leaving a soft trace in
- * the trace log rather than silently dropping them.
- */
-export declare const REJECTION_COOLDOWN_SIMILARITY_PENALTY = 0.5;
-export declare function networkMembershipPairKey(userId: string, networkId: string): string;
-/** Per-source cap for candidate premise matches. */
-export declare const PREMISE_MATCH_LIMIT_PER_SOURCE = 20;
-/** Resolve the source premise discovery cap from env, preserving 0 as an explicit disable switch. */
-export declare function getSourcePremiseDiscoveryLimit(): number;
-export declare function buildEvaluatorEvidenceKey(candidate: CandidateMatch): string;
-/**
- * Builds a compact text summary of the discoverer's profile and active intents
- * for use as profileContext in HyDE generation.
- * @param profile - The discoverer's profile data (identity, attributes)
- * @param intents - The discoverer's indexed intents (capped at 5)
- * @returns A context string, or undefined if no meaningful data is available
- */
-export declare function buildDiscovererContext(profile: SourceProfileData | null | undefined, intents: IndexedIntent[] | undefined): string | undefined;
-/**
- * Build a networkContexts map for the evaluator from a set of entities.
- * Fetches network data, checks permissions.contextInjection.discovery,
- * and renders context for eligible networks.
- */
-export declare function buildNetworkContexts(entities: EvaluatorEntity[], database: Pick<OpportunityGraphDatabase, 'getNetwork'>): Promise<Record<string, string>>;
-export type { Id };

package/dist/opportunities/opportunity.graph.shared.js

@@ -1,199 +0,0 @@
-/**
- * Shared vocabulary for the opportunity graph's nodes and modes.
- *
- * The nodes used to be closures inside `OpportunityGraphFactory.createGraph()`,
- * capturing `this` and the resolved thresholds. They are now top-level functions
- * that take an explicit {@link OpportunityGraphDeps} bag, so each node is
- * readable — and testable — on its own. This module owns the pieces more than
- * one of them needs: the dependency bag, the loggers, the trace wrapper, and the
- * small pure helpers.
- */
-import { ASK_USER_LOCK_SLACK_MS, askUserAnswerWindowMs } from '../negotiations/negotiation.module.js';
-import { protocolLogger } from '../shared/observability/protocol.logger.js';
-import { renderNetworkContext } from '../shared/network/metadata.renderer.js';
-import { requestContext } from '../shared/observability/request-context.js';
-export const logger = protocolLogger('OpportunityGraph');
-export const prepLog = protocolLogger('OpportunityGraph:Prep');
-export const scopeLog = protocolLogger('OpportunityGraph:Scope');
-export const resolveLog = protocolLogger('OpportunityGraph:Resolve');
-export const discoveryLog = protocolLogger('OpportunityGraph:Discovery');
-export const evaluationLog = protocolLogger('OpportunityGraph:Evaluation');
-export const negotiateLog = protocolLogger('OpportunityGraph:Negotiate');
-export const rankingLog = protocolLogger('OpportunityGraph:Ranking');
-export const introValidationLog = protocolLogger('OpportunityGraph:IntroValidation');
-export const introEvaluationLog = protocolLogger('OpportunityGraph:IntroEvaluation');
-export const persistLog = protocolLogger('OpportunityGraph:Persist');
-export const persistPathLog = protocolLogger('OpportunityGraph:Persist:PathSelect');
-export const persistDedupLog = protocolLogger('OpportunityGraph:Persist:Dedup');
-export const readLog = protocolLogger('OpportunityGraph:Read');
-export const updateLog = protocolLogger('OpportunityGraph:Update');
-export const deleteLog = protocolLogger('OpportunityGraph:Delete');
-export const sendLog = protocolLogger('OpportunityGraph:Send');
-export const negotiateExistingLog = protocolLogger('OpportunityGraph:NegotiateExisting');
-export const routingLog = protocolLogger('OpportunityGraph:Routing');
-/**
- * Error text can include provider response bodies, URLs, and credentials. Keep
- * observability useful by retaining only a conservative error class at this
- * boundary; detailed errors are intentionally not emitted from graph traces.
- */
-export function safeOpportunityGraphError(_error) {
-    return 'OpportunityEvaluationError: [redacted]';
-}
-/**
- * Wraps a graph node function to emit agent_start/agent_end trace events
- * at its boundaries so the frontend TRACE panel shows real-time progress.
- * @param traceName - Kebab-case agent name (e.g. "opportunity-prep")
- * @param nodeFn - The original node function
- * @param summaryFn - Optional function to derive a summary string from the node result
- */
-export function withNodeTrace(traceName, nodeFn, summaryFn) {
-    return async (state) => {
-        const traceEmitter = requestContext.getStore()?.traceEmitter;
-        const nodeStart = Date.now();
-        traceEmitter?.({ type: "agent_start", name: traceName });
-        try {
-            const result = await nodeFn(state);
-            const durationMs = Date.now() - nodeStart;
-            const summary = summaryFn?.(result) ?? undefined;
-            traceEmitter?.({ type: "agent_end", name: traceName, durationMs, summary });
-            return result;
-        }
-        catch (err) {
-            const durationMs = Date.now() - nodeStart;
-            const errMsg = safeOpportunityGraphError(err);
-            traceEmitter?.({ type: "agent_end", name: traceName, durationMs, summary: `error: ${errMsg}` });
-            throw err;
-        }
-    };
-}
-/** Shared trace summary: surface `error` when a node returned one. */
-export function errorSummary(result) {
-    const r = result;
-    return r?.error ? `error: ${r.error}` : undefined;
-}
-/** Time window for persist-node dedup. Suppresses a second opportunity with the same person while a recent one (within 30 days) is still in flight, so a person is not re-surfaced multiple times within a month (EDG-23). */
-export const DEDUP_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
-const ACTIVE_NEGOTIATION_TASK_STATES = new Set([
-    'submitted',
-    'working',
-    'input_required',
-    'waiting_for_agent',
-    'claimed',
-]);
-export function isActiveNegotiationTaskFresh(task) {
-    if (!ACTIVE_NEGOTIATION_TASK_STATES.has(task.state))
-        return false;
-    const freshnessMs = task.state === 'input_required'
-        ? askUserAnswerWindowMs() + ASK_USER_LOCK_SLACK_MS
-        : 5 * 60 * 1000;
-    return Date.now() - new Date(task.updatedAt).getTime() < freshnessMs;
-}
-export function triggerForOwner(opportunity, ownerUserId) {
-    return opportunity.detection.triggeredBy
-        ?? opportunity.actors.find((actor) => actor.userId === ownerUserId)?.intent;
-}
-export function belongsToOwnedIntent(opportunity, ownerUserId, triggerIntentId) {
-    return opportunity.detection.triggeredBy === triggerIntentId
-        || opportunity.actors.some((actor) => actor.userId === ownerUserId && actor.intent === triggerIntentId);
-}
-/**
- * IND-567: Cool-down window (ms) for cross-query rejection suppression.
- * Candidates with a recently rejected or stalled opportunity within this window
- * receive a similarity penalty during evaluation ranking. Default 7 days.
- * Override with DISCOVERY_REJECTION_COOLDOWN_DAYS (positive float).
- */
-const DEFAULT_REJECTION_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000;
-export function getRejectionCooldownMs() {
-    const raw = process.env.DISCOVERY_REJECTION_COOLDOWN_DAYS;
-    if (!raw)
-        return DEFAULT_REJECTION_COOLDOWN_MS;
-    const n = Number.parseFloat(raw);
-    return Number.isFinite(n) && n > 0 ? Math.round(n * 24 * 60 * 60 * 1000) : DEFAULT_REJECTION_COOLDOWN_MS;
-}
-/**
- * Similarity multiplier applied to candidates that fall within the rejection
- * cool-down window (IND-567). 0.5 halves their ranking score, typically
- * pushing them below the evaluation-batch cut while leaving a soft trace in
- * the trace log rather than silently dropping them.
- */
-export const REJECTION_COOLDOWN_SIMILARITY_PENALTY = 0.5;
-/** Default cap for source premises used by premise-to-premise discovery. Prevents BACKEND-5-style fan-out. */
-const DEFAULT_SOURCE_PREMISE_DISCOVERY_LIMIT = 40;
-/** NUL separator: it cannot occur inside an id, so the composite key is unambiguous. */
-const PAIR_KEY_SEPARATOR = String.fromCharCode(0);
-export function networkMembershipPairKey(userId, networkId) {
-    return userId + PAIR_KEY_SEPARATOR + networkId;
-}
-/** Per-source cap for candidate premise matches. */
-export const PREMISE_MATCH_LIMIT_PER_SOURCE = 20;
-/** Resolve the source premise discovery cap from env, preserving 0 as an explicit disable switch. */
-export function getSourcePremiseDiscoveryLimit() {
-    const raw = process.env.DISCOVERY_SOURCE_PREMISE_LIMIT;
-    if (raw === undefined || raw.trim() === '')
-        return DEFAULT_SOURCE_PREMISE_DISCOVERY_LIMIT;
-    const parsed = Number.parseInt(raw, 10);
-    return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_SOURCE_PREMISE_DISCOVERY_LIMIT;
-}
-export function buildEvaluatorEvidenceKey(candidate) {
-    return [
-        candidate.candidateUserId,
-        candidate.networkId,
-        candidate.candidateIntentId ?? candidate.candidatePremiseId ?? candidate.candidateContextId ?? candidate.sourceContextId ?? 'profile',
-    ].join(':');
-}
-/**
- * Builds a compact text summary of the discoverer's profile and active intents
- * for use as profileContext in HyDE generation.
- * @param profile - The discoverer's profile data (identity, attributes)
- * @param intents - The discoverer's indexed intents (capped at 5)
- * @returns A context string, or undefined if no meaningful data is available
- */
-export function buildDiscovererContext(profile, intents) {
-    const lines = [];
-    if (profile) {
-        const identity = profile.identity;
-        if (identity?.name || identity?.bio) {
-            lines.push(`Profile: ${[identity.name, identity.bio].filter(Boolean).join(', ')}`);
-        }
-        if (identity?.location) {
-            lines.push(`Location: ${identity.location}`);
-        }
-        if (profile.context) {
-            lines.push(`Context: ${profile.context}`);
-        }
-    }
-    if (intents?.length) {
-        // indexedIntents preserves DB order from getActiveIntents (newest first),
-        // so slice(0, 5) is deterministic without an explicit sort.
-        const capped = intents.slice(0, 5);
-        lines.push('');
-        lines.push('Active intents:');
-        for (const intent of capped) {
-            lines.push(`- ${intent.payload}`);
-        }
-    }
-    return lines.length > 0 ? lines.join('\n') : undefined;
-}
-/**
- * Build a networkContexts map for the evaluator from a set of entities.
- * Fetches network data, checks permissions.contextInjection.discovery,
- * and renders context for eligible networks.
- */
-export async function buildNetworkContexts(entities, database) {
-    const networkIds = [...new Set(entities.map((e) => e.networkId))];
-    const networks = await Promise.all(networkIds.map((nid) => database.getNetwork(nid).then((n) => ({ nid, n }))));
-    const contexts = {};
-    for (const { nid, n: network } of networks) {
-        if (!network)
-            continue;
-        const perms = (network.permissions ?? {});
-        const injection = perms.contextInjection;
-        if (injection?.discovery === false)
-            continue;
-        contexts[nid] = renderNetworkContext({
-            title: network.title,
-            prompt: network.prompt,
-        });
-    }
-    return contexts;
-}

package/dist/opportunities/opportunity.introducer-feature.d.ts

@@ -1,2 +0,0 @@
-/** Strict, default-off gate for finding opportunities on behalf of another user. */
-export declare function isIntroducerDiscoveryEnabled(): boolean;

package/dist/opportunities/opportunity.introducer-feature.js

@@ -1,4 +0,0 @@
-/** Strict, default-off gate for finding opportunities on behalf of another user. */
-export function isIntroducerDiscoveryEnabled() {
-    return process.env.INTRODUCER_DISCOVERY_ENABLED === "true";
-}

package/dist/opportunities/opportunity.introducer.d.ts

@@ -1,77 +0,0 @@
-/**
- * Introducer Discovery: proactive discovery of connector-flow opportunities
- * between a user's contacts.
- *
- * Selects top-N contacts from the user's personal network and runs scoped
- * HyDE discovery for each, creating latent introducer opportunities that
- * the user (as introducer) must approve before parties see them.
- */
-/** Maximum contacts to evaluate per maintenance cycle. */
-export declare const MAX_CONTACTS_PER_CYCLE = 5;
-/** Maximum candidate opportunities per contact. */
-export declare const MAX_CANDIDATES_PER_CONTACT = 3;
-/** Detection source value for introducer-discovered opportunities. */
-export declare const INTRODUCER_DISCOVERY_SOURCE: "introducer_discovery";
-/** A contact with their active intents, used for introducer discovery selection. */
-export interface ContactWithIntents {
-    userId: string;
-    /** Most recent intent updatedAt timestamp (ISO string or null). */
-    latestIntentAt: string | null;
-    /** Number of active intents this contact has. */
-    intentCount: number;
-}
-/** Database methods needed for introducer discovery contact selection. */
-export interface IntroducerDiscoveryDatabase {
-    /** Get the user's personal network ID. */
-    getPersonalIndexId(userId: string): Promise<string | null>;
-    /** Get contacts from a personal network with their intent freshness data. */
-    getContactsWithIntentFreshness(personalIndexId: string, ownerId: string, limit: number): Promise<ContactWithIntents[]>;
-}
-/** Queue interface for enqueuing introducer discovery jobs. */
-export interface IntroducerDiscoveryQueue {
-    addJob(data: {
-        intentId: string;
-        userId: string;
-        indexIds?: string[];
-        contactUserId?: string;
-    }, options?: {
-        priority?: number;
-        jobId?: string;
-    }): Promise<unknown>;
-}
-/** Result of a single introducer discovery cycle. */
-export interface IntroducerDiscoveryResult {
-    contactsEvaluated: number;
-    jobsEnqueued: number;
-    skippedReason?: string;
-}
-/**
- * Select top-N contacts for introducer discovery, sorted by intent freshness.
- * Contacts with no active intents are excluded.
- *
- * @param database - Database adapter with contact/intent queries
- * @param userId - The introducer user
- * @param limit - Max contacts to return (default MAX_CONTACTS_PER_CYCLE)
- * @returns Sorted contacts with intent data
- */
-export declare function selectContactsForDiscovery(database: IntroducerDiscoveryDatabase, userId: string, limit?: number): Promise<ContactWithIntents[]>;
-/**
- * Determine whether introducer discovery should run based on the current
- * connector-flow composition. Triggers when connector-flow count is below
- * the soft target.
- *
- * @param connectorFlowCount - Current number of connector-flow opportunities
- * @param connectorFlowTarget - Soft target (default 2)
- * @returns Whether introducer discovery should run
- */
-export declare function shouldRunIntroducerDiscovery(connectorFlowCount: number, connectorFlowTarget?: number): boolean;
-/**
- * Run introducer discovery for a user: select contacts, enqueue discovery jobs.
- * Each job uses onBehalfOfUserId so the opportunity graph treats the user as introducer.
- *
- * @param database - Database adapter for contact queries
- * @param queue - Queue for enqueuing discovery jobs
- * @param userId - The introducer user
- * @returns Summary of the discovery cycle
- */
-export declare function runIntroducerDiscovery(database: IntroducerDiscoveryDatabase, queue: IntroducerDiscoveryQueue, userId: string): Promise<IntroducerDiscoveryResult>;

package/dist/opportunities/opportunity.introducer.js

@@ -1,99 +0,0 @@
-/**
- * Introducer Discovery: proactive discovery of connector-flow opportunities
- * between a user's contacts.
- *
- * Selects top-N contacts from the user's personal network and runs scoped
- * HyDE discovery for each, creating latent introducer opportunities that
- * the user (as introducer) must approve before parties see them.
- */
-import { protocolLogger } from '../shared/observability/protocol.logger.js';
-const logger = protocolLogger('IntroducerDiscovery');
-/** Maximum contacts to evaluate per maintenance cycle. */
-export const MAX_CONTACTS_PER_CYCLE = 5;
-/** Maximum candidate opportunities per contact. */
-export const MAX_CANDIDATES_PER_CONTACT = 3;
-/** Detection source value for introducer-discovered opportunities. */
-export const INTRODUCER_DISCOVERY_SOURCE = 'introducer_discovery';
-/**
- * Select top-N contacts for introducer discovery, sorted by intent freshness.
- * Contacts with no active intents are excluded.
- *
- * @param database - Database adapter with contact/intent queries
- * @param userId - The introducer user
- * @param limit - Max contacts to return (default MAX_CONTACTS_PER_CYCLE)
- * @returns Sorted contacts with intent data
- */
-export async function selectContactsForDiscovery(database, userId, limit = MAX_CONTACTS_PER_CYCLE) {
-    const personalIndexId = await database.getPersonalIndexId(userId);
-    if (!personalIndexId) {
-        logger.verbose('No personal network found', { userId });
-        return [];
-    }
-    const contacts = await database.getContactsWithIntentFreshness(personalIndexId, userId, limit);
-    logger.verbose('Selected contacts for discovery', { userId, totalContacts: contacts.length, limit });
-    return contacts;
-}
-/**
- * Determine whether introducer discovery should run based on the current
- * connector-flow composition. Triggers when connector-flow count is below
- * the soft target.
- *
- * @param connectorFlowCount - Current number of connector-flow opportunities
- * @param connectorFlowTarget - Soft target (default 2)
- * @returns Whether introducer discovery should run
- */
-export function shouldRunIntroducerDiscovery(connectorFlowCount, connectorFlowTarget = 2) {
-    return connectorFlowCount < connectorFlowTarget;
-}
-/**
- * Run introducer discovery for a user: select contacts, enqueue discovery jobs.
- * Each job uses onBehalfOfUserId so the opportunity graph treats the user as introducer.
- *
- * @param database - Database adapter for contact queries
- * @param queue - Queue for enqueuing discovery jobs
- * @param userId - The introducer user
- * @returns Summary of the discovery cycle
- */
-export async function runIntroducerDiscovery(database, queue, userId) {
-    const personalIndexId = await database.getPersonalIndexId(userId);
-    if (!personalIndexId) {
-        return { contactsEvaluated: 0, jobsEnqueued: 0, skippedReason: 'no_personal_index' };
-    }
-    const contacts = await selectContactsForDiscovery(database, userId);
-    if (contacts.length === 0) {
-        return { contactsEvaluated: 0, jobsEnqueued: 0, skippedReason: 'no_contacts' };
-    }
-    const bucket = Math.floor(Date.now() / (12 * 60 * 60 * 1000)); // 12h dedup bucket
-    const results = await Promise.allSettled(contacts.map(async (contact) => {
-        // For each contact, we enqueue a discovery job using one of their intents
-        // The opportunity graph will use onBehalfOfUserId to discover on behalf of the contact
-        // while the userId (introducer) gets the introducer role
-        const jobId = `introducer-discovery-${userId}-${contact.userId}-${bucket}`;
-        try {
-            await queue.addJob({
-                intentId: `introducer:${contact.userId}`,
-                userId,
-                indexIds: [personalIndexId],
-                contactUserId: contact.userId,
-            }, { priority: 15, jobId });
-            return true;
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            if (/duplicate|already exists|job.*id/i.test(message)) {
-                logger.verbose('Job skipped (duplicate)', { userId, contactUserId: contact.userId, error: message });
-                return false;
-            }
-            throw err;
-        }
-    }));
-    for (const r of results) {
-        if (r.status === 'rejected') {
-            const errMsg = r.reason instanceof Error ? r.reason.message : String(r.reason);
-            logger.error('Job enqueue failed', { error: errMsg });
-        }
-    }
-    const jobsEnqueued = results.filter((r) => r.status === 'fulfilled' && r.value).length;
-    logger.info('Discovery cycle complete', { userId, contactsEvaluated: contacts.length, jobsEnqueued });
-    return { contactsEvaluated: contacts.length, jobsEnqueued };
-}

package/dist/opportunities/opportunity.labels.js

@@ -1,10 +0,0 @@
-/** Max chars for main text in minimal opportunity cards (chat tool payload). Full text shown so cards are not truncated. */
-export const MINIMAL_MAIN_TEXT_MAX_CHARS = 2000;
-/** Hardcoded button labels for opportunity cards (not LLM-generated). */
-export const PRIMARY_ACTION_LABEL_INTRODUCER = "Good match";
-export const PRIMARY_ACTION_LABEL_DEFAULT = "Start Chat";
-export const SECONDARY_ACTION_LABEL = "Skip";
-/** Returns the primary action label based on the viewer's role. */
-export function getPrimaryActionLabel(viewerRole) {
-    return viewerRole === "introducer" ? PRIMARY_ACTION_LABEL_INTRODUCER : PRIMARY_ACTION_LABEL_DEFAULT;
-}

package/dist/opportunities/opportunity.lifecycle.d.ts

@@ -1,63 +0,0 @@
-import type { Opportunity, OpportunityActor, OpportunityGraphDatabase } from '../shared/interfaces/database.interface.js';
-/** The mutation result shape returned by opportunity lifecycle graph nodes. */
-export interface OpportunityMutationResult {
-    success: boolean;
-    message?: string;
-    opportunityId?: string;
-    notified?: string[];
-    conversationId?: string;
-    error?: string;
-}
-/** Narrow persistence boundary for user-driven opportunity lifecycle actions. */
-export type OpportunityLifecyclePort = Pick<OpportunityGraphDatabase, 'getOpportunity' | 'getOrCreateDM' | 'stampOpportunityActorAction' | 'updateOpportunityActorApproval' | 'updateOpportunityStatus'>;
-/** Host callback used to notify an actor after an opportunity becomes visible to them. */
-export type QueueOpportunityNotificationFn = (opportunityId: string, recipientId: string, priority: 'immediate' | 'high' | 'low') => Promise<unknown>;
-type StatusTransitionPlan = {
-    kind: 'stamp_accepted';
-    counterpartUserId?: string;
-} | {
-    kind: 'set_terminal_status';
-    status: 'rejected' | 'expired';
-};
-type SendOpportunityPlan = {
-    sender: OpportunityActor;
-    recipients: OpportunityActor[];
-};
-/**
- * Applies status-transition admission rules before lifecycle persistence.
- * Acceptance is a two-party action: an actor that already acted cannot accept
- * again, while rejection and expiry remain available to any participating actor.
- */
-export declare function assessOpportunityStatusTransition(opportunity: Opportunity, actorUserId: string, newStatus: string | undefined): StatusTransitionPlan | OpportunityMutationResult;
-/**
- * Applies send admission and recipient-routing rules without performing writes.
- * Introducers, peers, and direct patient/party flows each reveal the next tier
- * to a distinct audience.
- */
-export declare function assessOpportunitySend(opportunity: Opportunity, actorUserId: string): SendOpportunityPlan | OpportunityMutationResult;
-/** Checks whether a caller may approve this opportunity's introducer gate. */
-export declare function assessIntroductionApproval(opportunity: Opportunity, actorUserId: string): OpportunityMutationResult | {
-    kind: 'approve';
-};
-/** Persists an admitted status transition, preserving accept-before-write DM ordering. */
-export declare function updateOpportunityLifecycle(database: OpportunityLifecyclePort, input: {
-    opportunityId?: string;
-    actorUserId: string;
-    newStatus?: string;
-}): Promise<OpportunityMutationResult>;
-/** Expires an opportunity after verifying the caller is one of its actors. */
-export declare function deleteOpportunityLifecycle(database: OpportunityLifecyclePort, input: {
-    opportunityId?: string;
-    actorUserId: string;
-}): Promise<OpportunityMutationResult>;
-/** Persists a send transition, then notifies only the actors exposed by its routing policy. */
-export declare function sendOpportunityLifecycle(database: OpportunityLifecyclePort, input: {
-    opportunityId?: string;
-    actorUserId: string;
-}, queueNotification?: QueueOpportunityNotificationFn): Promise<OpportunityMutationResult>;
-/** Approves an introducer gate before enqueuing the existing-opportunity negotiation. */
-export declare function approveOpportunityIntroduction(database: OpportunityLifecyclePort, input: {
-    opportunityId?: string;
-    actorUserId: string;
-}, queueNegotiateExisting?: (opportunityId: string, userId: string) => Promise<void>): Promise<OpportunityMutationResult>;
-export {};