@indexnetwork/protocol 6.12.0-rc.403.1 → 6.13.22-rc.405.1

package/dist/opportunity/domain/opportunity.state.js

@@ -0,0 +1,309 @@
+import { Annotation } from "@langchain/langgraph";
+/**
+ * Resolves the initial status for opportunities created in the persist node.
+ *
+ * Explicit `options.initialStatus` always wins (callers like the chat tool or
+ * maintenance scripts override per-call). When the caller leaves it
+ * undefined, the trigger drives the default:
+ * - 'orchestrator' → 'negotiating' (chat-driven; negotiations run before the
+ *   user sees a draft card).
+ * - 'ambient' (or any other trigger) → 'pending' (long-standing default for
+ *   queue- and intent-driven discovery).
+ *
+ * Lives here rather than in opportunity.graph.ts so unit tests can exercise
+ * it without pulling in the full graph (and the evaluator's LLM requirements).
+ *
+ * @param trigger - The graph invocation's trigger
+ * @param explicit - Caller-supplied initial status from options.initialStatus
+ */
+export function resolveInitialStatus(trigger, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    return trigger === 'orchestrator' ? 'negotiating' : 'pending';
+}
+/**
+ * Opportunity Graph State Annotation
+ */
+export const OpportunityGraphState = Annotation.Root({
+    // ─── Input Fields (Required) ───
+    userId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => '',
+    }),
+    searchQuery: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    networkId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /**
+     * Optional set of indexes discovery may search within (e.g. a network-scoped
+     * agent's reachable networks: the bound network plus the user's personal network).
+     * The scope node intersects this with the user's actual memberships. Ignored
+     * when `networkId` is set (single-network override). When unset, discovery
+     * spans all of the user's networks.
+     */
+    indexScope: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Optional intent to use as discovery source and for triggeredBy. When set, used for search text (if query empty) and persist. */
+    triggerIntentId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Optional: restrict discovery to this specific user ID only (direct connection). */
+    targetUserId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Optional: discover on behalf of this user (introducer flow). When set, prep/eval use this user's profile/intents; userId becomes the introducer. */
+    onBehalfOfUserId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    options: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => ({}),
+    }),
+    /**
+     * Which flow triggered this graph invocation. See {@link OpportunityTrigger}
+     * for the exact branch behavior and {@link resolveInitialStatus} for the
+     * persist default when `options.initialStatus` is unset.
+     *
+     * - 'ambient' (default): queue-driven, persist default `pending`, 5-min
+     *   park window, no streaming, ignores abort.
+     * - 'orchestrator': chat-driven, persist default `negotiating`, 60s park
+     *   window, streams `opportunity_draft_ready` events, honors abort.
+     */
+    trigger: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => 'ambient',
+    }),
+    /**
+     * Accepted opportunities the persist node discovered between the discoverer
+     * and a candidate actor (same pair, status='accepted'). The orchestrator
+     * branch populates this so the discover_opportunities tool (Task 7) can tell
+     * the LLM "these pairs are already connected, surface the existing chat
+     * rather than creating a new draft". Always empty for the ambient trigger.
+     *
+     * Left intentionally minimal — conversationId/URL resolution happens at
+     * Start Chat time (Task 8), not here.
+     */
+    dedupAlreadyAccepted: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /**
+     * Operation mode controls graph flow:
+     * - 'create': Existing discover pipeline (Prep → Scope → Discovery → Evaluation → Ranking → Persist)
+     * - 'create_introduction': Introduction path (validation → evaluation → persist) for chat-driven intros
+     * - 'continue_discovery': Pagination path (Prep → Evaluation → Ranking → Persist) using pre-loaded candidates
+     * - 'read': List opportunities filtered by userId and optionally networkId (fast path)
+     * - 'update': Change opportunity status (accept, reject, etc.)
+     * - 'delete': Expire/archive an opportunity
+     * - 'send': Promote latent opportunity to pending + queue notification
+     * - 'negotiate_existing': Load an existing opportunity by opportunityId and run bilateral negotiation.
+     *   Used after introducer approval to trigger the normal negotiation flow.
+     * - 'approve_introduction': Mark the caller as having approved a latent introducer opportunity,
+     *   then enqueue a negotiate_existing job for that opportunity.
+     *
+     * Defaults to 'create' for backward compatibility.
+     */
+    operationMode: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => 'create',
+    }),
+    /** Introduction mode: pre-gathered entities (profiles + intents per party). */
+    introductionEntities: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** Introduction mode: optional hint from the introducer. */
+    introductionHint: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** When set (e.g. chat scope), networkId must match this. */
+    requiredNetworkId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Set by intro_evaluation; used by persist to build manual detection and introducer actor. */
+    introductionContext: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Target opportunity ID for update/delete/send modes. */
+    opportunityId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** New status for update mode (e.g. 'accepted', 'rejected'). */
+    newStatus: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    // ─── Intermediate Fields (Accumulated) ───
+    /** User's indexed intents with hyde documents (from prep) */
+    indexedIntents: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** User's network memberships (from prep) */
+    userNetworks: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** Target indexes to search within (from scope) */
+    targetNetworks: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** Per-index relevancy scores for dedup tie-breaking. Background path: from intent_indexes. Chat path: transient from IntentIndexer. */
+    indexRelevancyScores: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => ({}),
+    }),
+    /** Whether discovery used intent (path A) or user context (path B/C). Used by persist for triggeredBy. In-memory routing state only; never persisted. */
+    discoverySource: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => 'intent',
+    }),
+    /** Resolved intent ID used for this discovery run (when discoverySource is 'intent'). Set by intent-resolution. */
+    resolvedTriggerIntentId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Asker's profile (from prep). Used for profile-as-source discovery and evaluation. */
+    sourceProfile: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => null,
+    }),
+    /** User's active premises with embeddings (from prep). Used for premise-to-premise discovery path D. */
+    sourcePremises: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** User context embeddings per network (from prep). Used for context-to-intent discovery. */
+    sourceContexts: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** Resolved intent is in at least one target index (path A vs C). */
+    resolvedIntentInIndex: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => false,
+    }),
+    /** Create-intent signal: when true, tool should return createIntentSuggested so agent can auto-call create_intent. */
+    createIntentSuggested: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => false,
+    }),
+    /** Suggested description for create_intent when createIntentSuggested is true. */
+    suggestedIntentDescription: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** HyDE embeddings per lens label (from discovery) */
+    hydeEmbeddings: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => ({}),
+    }),
+    /** Candidate matches from semantic search (from discovery) */
+    candidates: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** Candidates not yet evaluated (for pagination -- cached in Redis by caller). */
+    remainingCandidates: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** Discovery session ID for pagination (maps to Redis cache key). */
+    discoveryId: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => null,
+    }),
+    /** Evaluated candidates with scores (from evaluation; legacy) */
+    evaluatedCandidates: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** Evaluated opportunities with actors (from entity-bundle evaluator) */
+    evaluatedOpportunities: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    // ─── Output Fields (Overwrite per turn) ───
+    /** Final ranked and persisted opportunities */
+    opportunities: Annotation({
+        reducer: (curr, next) => next,
+        default: () => [],
+    }),
+    /** Discovery path: pairs skipped because an opportunity already exists between viewer and candidate (no duplicate created). */
+    existingBetweenActors: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => [],
+    }),
+    /** Typed persist-node counts used by queue telemetry. */
+    persistenceOutcome: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Positive exact-successor receipt for a fenced continuation. */
+    negotiationContinuationReceipt: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => undefined,
+    }),
+    /** Error message if any step fails */
+    error: Annotation({
+        reducer: (curr, next) => next,
+        default: () => undefined,
+    }),
+    /** Output for read mode: enriched list of opportunities. */
+    readResult: Annotation({
+        reducer: (curr, next) => next,
+        default: () => undefined,
+    }),
+    /** Output for update/delete/send modes. */
+    mutationResult: Annotation({
+        reducer: (curr, next) => next,
+        default: () => undefined,
+    }),
+    // ─── Trace Output ───
+    /**
+     * Accumulated trace entries from each graph node.
+     * Used for observability: surfaces internal processing steps (search query, HyDE strategies,
+     * candidates found, evaluation results) to the frontend.
+     */
+    trace: Annotation({
+        reducer: (curr, next) => [...curr, ...(next || [])],
+        default: () => [],
+    }),
+    /** Timing records for each agent invocation within this graph run. */
+    agentTimings: Annotation({
+        reducer: (acc, val) => [...acc, ...val],
+        default: () => [],
+    }),
+    /**
+     * Per-candidate negotiation records captured by `negotiateNode`. Populated
+     * regardless of accept/reject so the question generator sees a complete
+     * picture. Populated for ALL triggers (ambient + orchestrator) since the
+     * negotiate node's `onCandidateResolved` hook is unconditional; only the
+     * orchestrator streaming side-effects (opportunity_draft_ready emission)
+     * are trigger-gated. Empty when the negotiate node was skipped (no
+     * opportunities to negotiate).
+     */
+    discoveryNegotiations: Annotation({
+        reducer: (curr, next) => [...curr, ...(next || [])],
+        default: () => [],
+    }),
+    /** Aggregate counters across `discoveryNegotiations`. Built in the negotiate node. */
+    discoverySummary: Annotation({
+        reducer: (_curr, next) => next ?? null,
+        default: () => null,
+    }),
+});

package/dist/opportunity/domain/opportunity.utils.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Opportunity graph utilities: role derivation from corpus type.
+ * Used by the opportunity graph to map lens corpus to opportunity actor roles.
+ *
+ * With lens-based HyDE, strategy selection is handled automatically by the
+ * LensInferrer agent. This file provides corpus-to-role mapping for opportunity actors.
+ */
+import type { HydeTargetCorpus } from '../../shared/hyde/lens.inferrer.js';
+/** Actor roles in the opportunity model (agent / patient / peer). */
+export type OpportunityActorRole = 'agent' | 'patient' | 'peer';
+/** Result of mapping a corpus to source and candidate roles. */
+export interface DerivedRoles {
+    sourceRole: OpportunityActorRole;
+    candidateRole: OpportunityActorRole;
+}
+/**
+ * Derive actor roles from the corpus type of a lens match.
+ *
+ * When a candidate is found via:
+ * - "profiles" corpus → found by who they are → candidate can help → agent
+ * - "intents" corpus → found by what they need → candidate needs something → patient
+ *
+ * @param corpus - The target corpus that produced the match ('profiles' | 'intents')
+ * @returns Roles for the source (intent owner) and the candidate (matched user/intent)
+ */
+export declare function deriveRolesFromCorpus(corpus: HydeTargetCorpus): DerivedRoles;
+/**
+ * Validates opportunity actors: if an opportunity has an introducer, it must have
+ * one or two non-introducer actors (1 = 1:1 intro e.g. "I want to connect with X";
+ * 2 = introducer connecting two others).
+ *
+ * Also rejects self-matches — the same person occupying both sides of a
+ * connection. The discovery/persist pipeline trusts the LLM evaluator's actor
+ * list, which can collapse onto a single user; downstream readers then garble
+ * identity (e.g. a connect link/greeting rendered in one party's voice while the
+ * card shows the viewer "matched with themselves"). Two degenerate shapes are
+ * blocked here, at the single persist chokepoint:
+ *   - every userId-bearing non-introducer actor collapses to the same user,
+ *     e.g. `[X(agent), X(patient)]`
+ *   - an introducer who is also a participant ("Amina introduced you to Amina")
+ * Only `userId`-bearing actors are checked; role-only actors (legacy/tests) pass.
+ * Duplicate rows for one participant are allowed when at least one other distinct
+ * participant is present (some callers model multiple intents as multiple actor rows).
+ *
+ * @param actors - Array of actors with at least a role and optional userId
+ * @throws Error when the actor set is invalid
+ */
+export declare function validateOpportunityActors(actors: Array<{
+    userId?: string;
+    role: string;
+}>): void;
+/**
+ * Read-level ACL: whether a user is an actor on the opportunity and may fetch
+ * its details. Intentionally broader than `isActionableForViewer` — a user can
+ * read an opportunity they are not currently expected to act on (e.g. an agent
+ * viewing an accepted opportunity).
+ *
+ * The feed graph and debug controller chain both predicates: an opportunity only
+ * reaches the home feed if it passes `canUserSeeOpportunity` first, then
+ * `isActionableForViewer`. For `agent with introducer at pending`,
+ * `canUserSeeOpportunity` returns false (read gate blocks it), so the opportunity
+ * never surfaces even though `isActionableForViewer` Rule 4 would return true in
+ * isolation. This is by design — the agent is not granted read access through the
+ * home path until the introducer path completes (negotiation → accepted).
+ *
+ * Compact Visibility Rule (see `docs/design/opportunity-status-lifecycle.md`, §3.E):
+ * - Introducer or peer: always see.
+ * - Patient or party: see if (status is not latent, or there is no introducer).
+ * - Agent: see if (status is accepted/rejected/expired, or (status is not latent and there is no introducer)).
+ */
+export declare function canUserSeeOpportunity(actors: Array<{
+    userId: string;
+    role: string;
+}>, status: string, userId: string): boolean;
+/**
+ * Whether an opportunity should appear on the viewer's home feed (actionable =
+ * has a pending action for this user).
+ *
+ * Rules (see `docs/design/opportunity-status-lifecycle.md`, §3.E):
+ *
+ *   (1) `latent`, no introducer                   → all actors actionable
+ *   (2) `latent`, introducer `approved !== true`  → introducer only
+ *   (3) `latent`, introducer `approved === true`  → all non-introducer actors
+ *   (4) `pending` (any introducer config)         → non-introducer actors who have not acted.
+ *       Acting is per-user, not per-actor-row: re-detection can append duplicate
+ *       actor rows for the same user without `actedAt`, so any viewer row with
+ *       `actedAt` means the viewer has already acted.
+ *   (5) `accepted`/`rejected`/`expired`/`stalled`/`draft`/`negotiating`
+ *                                                 → never actionable
+ *
+ * The introducer approval signal is stored on the `introducer`-roled actor's
+ * `approved: boolean` field within the opportunity's `actors` JSONB. It flips
+ * from `false` to `true` when the introducer approves; status stays `latent`
+ * across the flip while a background negotiation runs.
+ */
+export declare function isActionableForViewer(actors: Array<{
+    userId: string;
+    role: string;
+    approved?: boolean;
+    actedAt?: string | null;
+}>, status: string, viewerId: string): boolean;
+/** Feed category for home composition. */
+export type FeedCategory = 'connection' | 'connector-flow' | 'expired';
+/** Soft targets for home feed composition. */
+export declare const FEED_SOFT_TARGETS: {
+    readonly connection: 3;
+    readonly connectorFlow: 2;
+    readonly expired: 2;
+};
+/**
+ * Classify an actionable opportunity into a feed category.
+ * Assumes the opportunity already passed isActionableForViewer or is expired.
+ *
+ * @param opp - Opportunity with actors and status
+ * @param viewerId - The viewing user's ID
+ * @returns Feed category
+ */
+export declare function classifyOpportunity(opp: {
+    actors: Array<{
+        userId: string;
+        role: string;
+    }>;
+    status: string;
+}, viewerId: string): FeedCategory;
+/**
+ * Select opportunities for the home feed using soft composition targets.
+ * Fills each category up to its target, then redistributes unused slots
+ * to categories that have more items available. Preserves input order.
+ *
+ * @param opportunities - Pre-sorted opportunities (by confidence/recency)
+ * @param viewerId - The viewing user's ID
+ * @returns Composition-balanced subset
+ */
+export declare function selectByComposition<T extends {
+    actors: Array<{
+        userId: string;
+        role: string;
+    }>;
+    status: string;
+}>(opportunities: T[], viewerId: string): T[];
+/**
+ * Deduplicate opportunities so each counterpart appears at most once.
+ * Keeps the opportunity with the highest interpretation.confidence per
+ * counterpart userId. On ties, the first encountered wins (stable).
+ *
+ * Counterpart = first actor whose userId !== viewerId and role !== 'introducer'.
+ * Opportunities without a derivable counterpart pass through undeduped.
+ *
+ * @param opportunities - Pre-sorted opportunities (e.g. by confidence/recency)
+ * @param viewerId - The viewing user's ID
+ * @returns Deduped subset preserving original input order among winners
+ */
+export declare function deduplicateByPerson<T extends {
+    actors: Array<{
+        userId: string;
+        role: string;
+    }>;
+    interpretation?: {
+        confidence?: number;
+    } | null;
+}>(opportunities: T[], viewerId: string): T[];
+/**
+ * Days a digest-delivered opportunity stays suppressed before it becomes
+ * eligible for a "still open" reminder re-show (when nothing fresh exists).
+ */
+export declare const DIGEST_REDELIVERY_COOLDOWN_DAYS = 5;
+/** Committed delivery row shape consumed by {@link selectDigestCandidates}. */
+export interface DigestDeliveredRow {
+    opportunityId: string;
+    deliveredAtStatus: string;
+    deliveredAt: Date;
+}
+/**
+ * Cross-day digest suppression for scheduled-brief candidates.
+ *
+ * Three rules, applied in order:
+ * 1. **Accepted-counterpart suppression** — a direct-connection candidate whose
+ *    counterpart the viewer has already connected with (an `accepted`
+ *    opportunity exists with that person) is dropped permanently. A new
+ *    discovery run re-minting the same person must not resurface them.
+ *    Connector-flow candidates (viewer is the introducer) are exempt: being
+ *    connected with someone doesn't make an intro ask on their behalf stale.
+ * 2. **Delivery-ledger dedup** — candidates with a committed delivery row at
+ *    the same `(opportunityId, status)` key have already been shown. While any
+ *    fresh (never-shown) candidate exists, shown ones are dropped entirely.
+ * 3. **Cooldown re-show** — when *no* fresh candidate survives, already-shown
+ *    candidates whose latest delivery is at least `cooldownDays` old are
+ *    returned instead, least-recently-shown first, flagged via
+ *    `redeliveryIds` so the digest can frame them as reminders.
+ *
+ * Pure function — callers fetch accepted counterparts and ledger rows.
+ *
+ * @param candidates - Deduped, confidence-ordered digest candidates.
+ * @param opts.viewerId - The digest recipient.
+ * @param opts.acceptedCounterpartIds - userIds the viewer already connected with.
+ * @param opts.deliveredRows - Committed ledger rows for the candidate ids.
+ * @param opts.now - Clock override for tests.
+ * @param opts.cooldownDays - Cooldown override (default {@link DIGEST_REDELIVERY_COOLDOWN_DAYS}).
+ * @returns Surviving pool plus the set of candidate ids that are cooldown re-shows.
+ */
+export declare function selectDigestCandidates<T extends {
+    id: string;
+    status: string;
+    actors: Array<{
+        userId: string;
+        role: string;
+    }>;
+}>(candidates: T[], opts: {
+    viewerId: string;
+    acceptedCounterpartIds: ReadonlySet<string>;
+    deliveredRows: DigestDeliveredRow[];
+    now?: Date;
+    cooldownDays?: number;
+}): {
+    pool: T[];
+    redeliveryIds: Set<string>;
+};