@indexnetwork/protocol 14.3.2-rc.477.1 → 16.1.1-rc.478.1

package/dist/opportunities/application/opportunity.graph.modes.d.ts

@@ -0,0 +1,538 @@
+/**
+ * The opportunity operations that are not discovery.
+ *
+ * These used to be graph nodes reached through an `operationMode` conditional
+ * edge at START — nine one-node paths sharing a state machine they never used.
+ * They are plain async functions now; callers invoke the one they mean. Only
+ * the discovery pipeline still needs a graph.
+ *
+ * Each returns the same shape the corresponding node returned, so callers read
+ * `readResult` / `mutationResult` exactly as before.
+ */
+import type { Id, NegotiationContinuationReceipt } from '../../shared/interfaces/database.interface.js';
+import type { DebugMetaAgent } from '../../agents/index.js';
+import type { EvaluatedOpportunity, EvaluatedOpportunityActor } from '../domain/opportunity.state.js';
+import type { EvaluatorEntity } from './opportunity.evaluator.js';
+import type { OpportunityMutationResult } from './opportunity.lifecycle.js';
+import { type OpportunityGraphDeps, type OpportunityState } from './opportunity.graph.shared.js';
+/** Identifies the caller and the opportunity every mutation mode acts on. */
+export interface OpportunityMutationRequest {
+    userId: Id<'users'>;
+    opportunityId: string | undefined;
+}
+/** Shape the update/delete/send/approve modes return. */
+export interface OpportunityMutationOutcome {
+    mutationResult: OpportunityMutationResult;
+}
+/**
+ * Read mode: list opportunities for the user, optionally filtered by networkId.
+ * Fast path — no LLM calls.
+ */
+export declare function readOpportunities(deps: Pick<OpportunityGraphDeps, 'database'>, request: {
+    userId: Id<'users'>;
+    networkId?: Id<'networks'>;
+}): Promise<{
+    readResult: {
+        count: number;
+        message: string;
+        opportunities: {
+            id: string;
+            indexName: string;
+            connectedWith: string[];
+            suggestedBy: string | null;
+            reasoning: string;
+            status: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+            category: string;
+            confidence: number | null;
+            source: string | null;
+        }[];
+    };
+}>;
+/**
+ * Update mode: change opportunity status (accept, reject, etc.).
+ * For 'accepted', enforces the self-accept guard: the caller's actor entry
+ * must not already have `actedAt` set — i.e. the caller has not yet been
+ * the one to advance this opportunity's state. Stamps `actedAt` on accept
+ * atomically with the status change via `stampOpportunityActorAction`.
+ */
+export declare function updateOpportunityStatus(deps: Pick<OpportunityGraphDeps, 'database'>, request: OpportunityMutationRequest & {
+    newStatus: string | undefined;
+}): Promise<OpportunityMutationOutcome>;
+/** Delete mode: expire/archive an opportunity. */
+export declare function deleteOpportunity(deps: Pick<OpportunityGraphDeps, 'database'>, request: OpportunityMutationRequest): Promise<OpportunityMutationOutcome>;
+/** Send mode: promote a latent or draft opportunity to pending + queue notification. */
+export declare function sendOpportunity(deps: Pick<OpportunityGraphDeps, 'database' | 'queueNotification'>, request: OpportunityMutationRequest): Promise<OpportunityMutationOutcome>;
+/**
+ * Approve-introduction mode.
+ * Called by the introducer to approve a latent introducer-pattern opportunity.
+ * Sets approved=true on the introducer actor (status stays latent), then
+ * enqueues a negotiate_existing job so the parties negotiate normally.
+ */
+export declare function approveIntroduction(deps: Pick<OpportunityGraphDeps, 'database' | 'queueNegotiateExisting'>, request: OpportunityMutationRequest): Promise<OpportunityMutationOutcome>;
+/**
+ * Negotiate-existing mode: load an existing opportunity by ID and run bilateral negotiation.
+ * Used after introducer approval to trigger the normal negotiation flow for a latent opportunity.
+ */
+export declare function negotiateExisting(deps: Pick<OpportunityGraphDeps, 'database' | 'negotiationGraph' | 'queueNotification'>, request: OpportunityMutationRequest & {
+    continuation?: OpportunityState['options']['negotiationContinuation'];
+}): Promise<{
+    negotiationContinuationReceipt?: NegotiationContinuationReceipt;
+    error?: string;
+}>;
+/** What the caller supplies to create an introduction. */
+export interface IntroductionRequest {
+    userId: Id<'users'>;
+    networkId?: Id<'networks'>;
+    /** Pre-gathered entities (profiles + intents per party). */
+    introductionEntities: EvaluatorEntity[];
+    /** Optional hint from the introducer. */
+    introductionHint?: string;
+    /** When set (e.g. chat scope), networkId must match this. */
+    requiredNetworkId?: Id<'networks'>;
+    options?: Partial<OpportunityState['options']>;
+}
+/**
+ * Introduction mode: validate → evaluate → persist.
+ *
+ * Validation gates on scope and membership; evaluation asks the evaluator to
+ * justify the pairing (falling back to the introducer's own word); persistence
+ * reuses the discovery pipeline's persist stage.
+ */
+export declare function createIntroduction(deps: OpportunityGraphDeps, request: IntroductionRequest): Promise<{
+    error?: string;
+    trace?: Array<{
+        node: string;
+        detail?: string;
+        data?: Record<string, unknown>;
+    }>;
+    opportunities: never[];
+    evaluatedOpportunities: never[];
+    agentTimings: never[];
+} | {
+    opportunities: never[];
+    persistenceOutcome: {
+        evaluatedCount: number;
+        createdCount: number;
+        reactivatedCount: number;
+        sameTriggerDuplicateSuppressions: number;
+        pairActiveNegotiationSuppressions: number;
+        crossTriggerAllowedCount: number;
+        finalAtomicConflictCount: number;
+    };
+    existingBetweenActors?: undefined;
+    trace?: undefined;
+    error?: undefined;
+    evaluatedOpportunities: never[];
+    agentTimings: never[];
+    introductionContext?: undefined;
+    options?: undefined;
+} | {
+    opportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+    existingBetweenActors: {
+        candidateUserId: Id<"users">;
+        networkId: Id<"networks">;
+        existingOpportunityId?: Id<"opportunities">;
+        existingStatus?: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        reason?: "same_trigger_recent_duplicate" | "pair_active_negotiation" | "final_atomic_conflict";
+        existingTriggerIntentId?: string;
+    }[];
+    persistenceOutcome: {
+        evaluatedCount: number;
+        createdCount: number;
+        reactivatedCount: number;
+        sameTriggerDuplicateSuppressions: number;
+        pairActiveNegotiationSuppressions: number;
+        crossTriggerAllowedCount: number;
+        finalAtomicConflictCount: number;
+    };
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            created: number;
+            reactivated: number;
+            existingSkipped: number;
+            totalOutput: number;
+            persistenceOutcome: {
+                evaluatedCount: number;
+                createdCount: number;
+                reactivatedCount: number;
+                sameTriggerDuplicateSuppressions: number;
+                pairActiveNegotiationSuppressions: number;
+                crossTriggerAllowedCount: number;
+                finalAtomicConflictCount: number;
+            };
+            durationMs: number;
+        };
+    }[];
+    error?: undefined;
+    evaluatedOpportunities: never[];
+    agentTimings: never[];
+    introductionContext?: undefined;
+    options?: undefined;
+} | {
+    opportunities: never[];
+    existingBetweenActors: never[];
+    error: string;
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            error: string;
+        };
+    }[];
+    persistenceOutcome?: undefined;
+    evaluatedOpportunities: never[];
+    agentTimings: never[];
+    introductionContext?: undefined;
+    options?: undefined;
+} | {
+    opportunities: never[];
+    persistenceOutcome: {
+        evaluatedCount: number;
+        createdCount: number;
+        reactivatedCount: number;
+        sameTriggerDuplicateSuppressions: number;
+        pairActiveNegotiationSuppressions: number;
+        crossTriggerAllowedCount: number;
+        finalAtomicConflictCount: number;
+    };
+    existingBetweenActors?: undefined;
+    trace?: undefined;
+    error: string;
+    evaluatedOpportunities: never[];
+    agentTimings: never[];
+    introductionContext?: undefined;
+    options?: undefined;
+} | {
+    opportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+    existingBetweenActors: {
+        candidateUserId: Id<"users">;
+        networkId: Id<"networks">;
+        existingOpportunityId?: Id<"opportunities">;
+        existingStatus?: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        reason?: "same_trigger_recent_duplicate" | "pair_active_negotiation" | "final_atomic_conflict";
+        existingTriggerIntentId?: string;
+    }[];
+    persistenceOutcome: {
+        evaluatedCount: number;
+        createdCount: number;
+        reactivatedCount: number;
+        sameTriggerDuplicateSuppressions: number;
+        pairActiveNegotiationSuppressions: number;
+        crossTriggerAllowedCount: number;
+        finalAtomicConflictCount: number;
+    };
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            created: number;
+            reactivated: number;
+            existingSkipped: number;
+            totalOutput: number;
+            persistenceOutcome: {
+                evaluatedCount: number;
+                createdCount: number;
+                reactivatedCount: number;
+                sameTriggerDuplicateSuppressions: number;
+                pairActiveNegotiationSuppressions: number;
+                crossTriggerAllowedCount: number;
+                finalAtomicConflictCount: number;
+            };
+            durationMs: number;
+        };
+    }[];
+    error: string;
+    evaluatedOpportunities: never[];
+    agentTimings: never[];
+    introductionContext?: undefined;
+    options?: undefined;
+} | {
+    opportunities: never[];
+    persistenceOutcome: {
+        evaluatedCount: number;
+        createdCount: number;
+        reactivatedCount: number;
+        sameTriggerDuplicateSuppressions: number;
+        pairActiveNegotiationSuppressions: number;
+        crossTriggerAllowedCount: number;
+        finalAtomicConflictCount: number;
+    };
+    existingBetweenActors?: undefined;
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            error: string;
+        };
+    }[];
+    error?: undefined;
+    evaluatedOpportunities: {
+        actors: EvaluatedOpportunityActor[];
+        score: number;
+        reasoning: string;
+    }[];
+    introductionContext: {
+        createdByName: string | undefined;
+    };
+    options: {
+        initialStatus: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        negotiationContinuation?: import("../../shared/interfaces/database.negotiation.js").NegotiationContinuationExecution;
+        limit?: number;
+        lenses?: import("../../discovery/lens.inferrer.js").Lens[];
+        hydeDescription?: string;
+        existingOpportunities?: string;
+        conversationId?: string;
+        negotiateTimeoutMs?: number;
+    };
+    agentTimings: DebugMetaAgent[];
+} | {
+    opportunities: never[];
+    persistenceOutcome?: undefined;
+    existingBetweenActors?: undefined;
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            error: string;
+        };
+    }[];
+    error?: undefined;
+    evaluatedOpportunities: {
+        actors: EvaluatedOpportunityActor[];
+        score: number;
+        reasoning: string;
+    }[];
+    introductionContext: {
+        createdByName: string | undefined;
+    };
+    options: {
+        initialStatus: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        negotiationContinuation?: import("../../shared/interfaces/database.negotiation.js").NegotiationContinuationExecution;
+        limit?: number;
+        lenses?: import("../../discovery/lens.inferrer.js").Lens[];
+        hydeDescription?: string;
+        existingOpportunities?: string;
+        conversationId?: string;
+        negotiateTimeoutMs?: number;
+    };
+    agentTimings: DebugMetaAgent[];
+} | {
+    opportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+    existingBetweenActors: {
+        candidateUserId: Id<"users">;
+        networkId: Id<"networks">;
+        existingOpportunityId?: Id<"opportunities">;
+        existingStatus?: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        reason?: "same_trigger_recent_duplicate" | "pair_active_negotiation" | "final_atomic_conflict";
+        existingTriggerIntentId?: string;
+    }[];
+    persistenceOutcome: {
+        evaluatedCount: number;
+        createdCount: number;
+        reactivatedCount: number;
+        sameTriggerDuplicateSuppressions: number;
+        pairActiveNegotiationSuppressions: number;
+        crossTriggerAllowedCount: number;
+        finalAtomicConflictCount: number;
+    };
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            created: number;
+            reactivated: number;
+            existingSkipped: number;
+            totalOutput: number;
+            persistenceOutcome: {
+                evaluatedCount: number;
+                createdCount: number;
+                reactivatedCount: number;
+                sameTriggerDuplicateSuppressions: number;
+                pairActiveNegotiationSuppressions: number;
+                crossTriggerAllowedCount: number;
+                finalAtomicConflictCount: number;
+            };
+            durationMs: number;
+        };
+    }[];
+    error?: undefined;
+    evaluatedOpportunities: {
+        actors: EvaluatedOpportunityActor[];
+        score: number;
+        reasoning: string;
+    }[];
+    introductionContext: {
+        createdByName: string | undefined;
+    };
+    options: {
+        initialStatus: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        negotiationContinuation?: import("../../shared/interfaces/database.negotiation.js").NegotiationContinuationExecution;
+        limit?: number;
+        lenses?: import("../../discovery/lens.inferrer.js").Lens[];
+        hydeDescription?: string;
+        existingOpportunities?: string;
+        conversationId?: string;
+        negotiateTimeoutMs?: number;
+    };
+    agentTimings: DebugMetaAgent[];
+} | {
+    opportunities: never[];
+    existingBetweenActors: never[];
+    error: string;
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            error: string;
+        };
+    }[];
+    persistenceOutcome?: undefined;
+    evaluatedOpportunities: {
+        actors: EvaluatedOpportunityActor[];
+        score: number;
+        reasoning: string;
+    }[];
+    introductionContext: {
+        createdByName: string | undefined;
+    };
+    options: {
+        initialStatus: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        negotiationContinuation?: import("../../shared/interfaces/database.negotiation.js").NegotiationContinuationExecution;
+        limit?: number;
+        lenses?: import("../../discovery/lens.inferrer.js").Lens[];
+        hydeDescription?: string;
+        existingOpportunities?: string;
+        conversationId?: string;
+        negotiateTimeoutMs?: number;
+    };
+    agentTimings: DebugMetaAgent[];
+} | {
+    opportunities: never[];
+    persistenceOutcome: {
+        evaluatedCount: number;
+        createdCount: number;
+        reactivatedCount: number;
+        sameTriggerDuplicateSuppressions: number;
+        pairActiveNegotiationSuppressions: number;
+        crossTriggerAllowedCount: number;
+        finalAtomicConflictCount: number;
+    };
+    existingBetweenActors?: undefined;
+    trace?: undefined;
+    error?: undefined;
+    evaluatedOpportunities: EvaluatedOpportunity[];
+    introductionContext: {
+        createdByName: string | undefined;
+    };
+    options: {
+        initialStatus: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        negotiationContinuation?: import("../../shared/interfaces/database.negotiation.js").NegotiationContinuationExecution;
+        limit?: number;
+        lenses?: import("../../discovery/lens.inferrer.js").Lens[];
+        hydeDescription?: string;
+        existingOpportunities?: string;
+        conversationId?: string;
+        negotiateTimeoutMs?: number;
+    };
+    agentTimings: DebugMetaAgent[];
+} | {
+    opportunities: never[];
+    persistenceOutcome?: undefined;
+    existingBetweenActors?: undefined;
+    trace?: undefined;
+    error?: undefined;
+    evaluatedOpportunities: EvaluatedOpportunity[];
+    introductionContext: {
+        createdByName: string | undefined;
+    };
+    options: {
+        initialStatus: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        negotiationContinuation?: import("../../shared/interfaces/database.negotiation.js").NegotiationContinuationExecution;
+        limit?: number;
+        lenses?: import("../../discovery/lens.inferrer.js").Lens[];
+        hydeDescription?: string;
+        existingOpportunities?: string;
+        conversationId?: string;
+        negotiateTimeoutMs?: number;
+    };
+    agentTimings: DebugMetaAgent[];
+}>;
+/**
+ * Introduction validation: network scope, membership for introducer and all
+ * party users, and no existing opportunity between the parties.
+ */
+export declare function validateIntroduction(deps: Pick<OpportunityGraphDeps, 'database'>, state: Pick<OpportunityState, 'userId' | 'networkId' | 'introductionEntities' | 'requiredNetworkId'>): Promise<{
+    error?: string;
+    trace?: Array<{
+        node: string;
+        detail?: string;
+        data?: Record<string, unknown>;
+    }>;
+}>;
+/**
+ * Introduction evaluation: runs the entity-bundle evaluator and sets
+ * evaluatedOpportunities (one) + introductionContext.
+ */
+export declare function evaluateIntroduction(deps: Pick<OpportunityGraphDeps, 'database' | 'evaluatorAgent'>, state: Pick<OpportunityState, 'userId' | 'networkId' | 'introductionEntities' | 'introductionHint' | 'options' | 'error'>): Promise<{
+    evaluatedOpportunities: never[];
+    agentTimings: never[];
+    error?: undefined;
+    introductionContext?: undefined;
+    options?: undefined;
+    trace?: undefined;
+} | {
+    evaluatedOpportunities: never[];
+    error: string;
+    agentTimings: never[];
+    introductionContext?: undefined;
+    options?: undefined;
+    trace?: undefined;
+} | {
+    evaluatedOpportunities: {
+        actors: EvaluatedOpportunityActor[];
+        score: number;
+        reasoning: string;
+    }[];
+    introductionContext: {
+        createdByName: string | undefined;
+    };
+    options: {
+        initialStatus: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        negotiationContinuation?: import("../../shared/interfaces/database.negotiation.js").NegotiationContinuationExecution;
+        limit?: number;
+        lenses?: import("../../discovery/lens.inferrer.js").Lens[];
+        hydeDescription?: string;
+        existingOpportunities?: string;
+        conversationId?: string;
+        negotiateTimeoutMs?: number;
+    };
+    agentTimings: DebugMetaAgent[];
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            error: string;
+        };
+    }[];
+    error?: undefined;
+} | {
+    evaluatedOpportunities: EvaluatedOpportunity[];
+    introductionContext: {
+        createdByName: string | undefined;
+    };
+    options: {
+        initialStatus: import("../../shared/interfaces/database.entities.js").OpportunityStatus;
+        negotiationContinuation?: import("../../shared/interfaces/database.negotiation.js").NegotiationContinuationExecution;
+        limit?: number;
+        lenses?: import("../../discovery/lens.inferrer.js").Lens[];
+        hydeDescription?: string;
+        existingOpportunities?: string;
+        conversationId?: string;
+        negotiateTimeoutMs?: number;
+    };
+    agentTimings: DebugMetaAgent[];
+    error?: undefined;
+    trace?: undefined;
+}>;