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

package/dist/opportunity/domain/opportunity.safe-presentation.js

@@ -0,0 +1,102 @@
+/**
+ * Shared safe-presentation primitive for all user-facing opportunity surfaces.
+ *
+ * Historically every surface (home feed, list/discover cards, minimal chat
+ * cards, notification emails/Telegram, chat context, delivery cards) invented
+ * its own fallback chain for the case where genuine LLM presenter output is
+ * unavailable — some sliced raw `interpretation.reasoning` with no
+ * sanitization at all. This module is the single standard:
+ *
+ *   raw reasoning
+ *     → whitespace-normalize
+ *     → viewer-centric rewrite (incl. UUID stripping + introducer-mention stripping)
+ *     → boundary-aware truncation
+ *     → per-surface empty-text default
+ *
+ * Surfaces choose *policy* (send a sanitized fallback vs skip entirely) via
+ * `allowFallback`; they no longer choose (or forget) sanitization steps.
+ *
+ * See `.agents/skills/review-opportunity-presentation/SKILL.md` for the review
+ * checklist this module exists to satisfy.
+ */
+import { truncateAtBoundary, viewerCentricCardSummary } from "./opportunity.presentation.js";
+import { stripUnsupportedOpportunityClaims } from "./opportunity.claim-safety.js";
+/** Default max length for fallback summaries (matches presenter internal fallback). */
+export const SAFE_FALLBACK_MAX_CHARS = 300;
+/** Default copy when no reasoning text is available at all. */
+export const DEFAULT_EMPTY_FALLBACK_TEXT = "A promising connection.";
+/** Default headline for fallback presentations (matches presenter internal fallback). */
+export const DEFAULT_FALLBACK_HEADLINE = "A promising connection";
+/** Default CTA for fallback presentations (matches presenter internal fallback). */
+export const DEFAULT_FALLBACK_ACTION = "Take a look and decide whether to reach out.";
+/**
+ * Produce safe user-facing fallback copy from raw match reasoning.
+ *
+ * This is the ONE sanitization standard: UUID stripping, introducer-mention
+ * stripping, and viewer-centric rewrite (via {@link viewerCentricCardSummary}),
+ * followed by whitespace normalization and boundary-aware truncation (via
+ * {@link truncateAtBoundary}). Never returns raw reasoning verbatim beyond
+ * these guarantees, and never returns an empty string.
+ *
+ * @param rawReasoning - Raw `interpretation.reasoning` / `matchReason` text (may be null/undefined).
+ * @param opts - Per-surface knobs (names for rewrite, max length, empty-text copy).
+ */
+export function safeFallbackSummary(rawReasoning, opts = {}) {
+    const emptyText = opts.emptyText ?? DEFAULT_EMPTY_FALLBACK_TEXT;
+    const maxChars = opts.maxChars ?? SAFE_FALLBACK_MAX_CHARS;
+    const normalized = (rawReasoning ?? "").replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return emptyText;
+    const claimSafeInput = stripUnsupportedOpportunityClaims(normalized);
+    if (!claimSafeInput)
+        return emptyText;
+    // viewerCentricCardSummary handles UUID stripping, introducer-mention
+    // stripping, and the viewer-centric rewrite. Pass Infinity so truncation is
+    // handled by boundary-aware logic below instead of a mid-word hard slice.
+    const rewritten = viewerCentricCardSummary(claimSafeInput, opts.counterpartName ?? "", Number.POSITIVE_INFINITY, opts.viewerName, opts.introducerName ?? undefined);
+    // Claim validation intentionally runs after viewer-centric rewriting: rewrite
+    // heuristics may select or join different source sentences, and the final
+    // user-facing sentence set is what must be safe.
+    const claimSafe = stripUnsupportedOpportunityClaims(rewritten);
+    const truncated = truncateAtBoundary(claimSafe, maxChars);
+    return truncated || emptyText;
+}
+/**
+ * Resolve the safe user-facing presentation for an opportunity, or signal skip.
+ *
+ * Resolution order:
+ * 1. Genuine presenter output (`homeCardPresentation` present, non-empty, and
+ *    NOT tagged `isFallback` by the presenter) — claim-validated before return.
+ * 2. Otherwise, if `allowFallback` (default true): sanitized fallback copy
+ *    built from `matchReason` / `interpretation.reasoning` via
+ *    {@link safeFallbackSummary}.
+ * 3. Otherwise `null` — the surface must skip this opportunity.
+ *
+ * Raw `interpretation.reasoning` / `matchReason` never reaches the caller
+ * unsanitized through this function.
+ */
+export function getSafePresentationOrSkip(source, opts = {}) {
+    const candidate = source.homeCardPresentation;
+    if (candidate?.personalizedSummary?.trim() && !candidate.isFallback) {
+        const summary = stripUnsupportedOpportunityClaims(candidate.personalizedSummary);
+        if (summary) {
+            return {
+                headline: stripUnsupportedOpportunityClaims(candidate.headline) ||
+                    DEFAULT_FALLBACK_HEADLINE,
+                summary,
+                suggestedAction: stripUnsupportedOpportunityClaims(candidate.suggestedAction) ||
+                    DEFAULT_FALLBACK_ACTION,
+                isFallback: false,
+            };
+        }
+    }
+    if (opts.allowFallback === false)
+        return null;
+    const rawReasoning = source.matchReason ?? source.interpretation?.reasoning ?? "";
+    return {
+        headline: DEFAULT_FALLBACK_HEADLINE,
+        summary: safeFallbackSummary(rawReasoning, opts),
+        suggestedAction: DEFAULT_FALLBACK_ACTION,
+        isFallback: true,
+    };
+}

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

@@ -0,0 +1,519 @@
+import type { Id, NegotiationContinuationExecution, NegotiationContinuationReceipt, OpportunityStatus, Opportunity } from '../../shared/interfaces/database.interface.js';
+import type { Lens } from '../../shared/interfaces/embedder.interface.js';
+import type { EvaluatorEntity } from '../application/opportunity.evaluator.js';
+import type { DebugMetaAgent } from '../../capabilities/participant-agents.debug.facade.js';
+import type { OpportunityEvidence } from '../../shared/schemas/network-assignment.schema.js';
+import type { DiscoverySummary } from "../../shared/schemas/discovery-question.schema.js";
+/**
+ * Opportunity Graph State (Linear Multi-Step Workflow)
+ *
+ * Flow: Prep → Scope → Discovery → Evaluation → Ranking → Persist → END
+ *
+ * Following the intent graph pattern with Annotation-based state management.
+ */
+/** Asker's profile shape (identity + context). Used by sourceProfile annotation. */
+export interface SourceProfileData {
+    identity?: {
+        name?: string;
+        bio?: string;
+        location?: string;
+    };
+    context?: string;
+}
+/**
+ * Indexed intent with hyde document (from prep node)
+ */
+export interface IndexedIntent {
+    intentId: Id<'intents'>;
+    payload: string;
+    summary?: string;
+    hydeDocumentId?: string;
+    hydeEmbedding?: number[];
+    indexes: Id<'networks'>[];
+}
+/**
+ * Target index for search (from scope node)
+ */
+export interface TargetNetwork {
+    networkId: Id<'networks'>;
+    title: string;
+    memberCount: number;
+}
+/**
+ * Candidate match from discovery (semantic search).
+ */
+export interface CandidateMatch {
+    candidateUserId: Id<'users'>;
+    candidateIntentId?: Id<'intents'>;
+    /** Source premise that produced this candidate (set when discoverySource is 'premise-similarity'). */
+    sourcePremiseId?: Id<'premises'>;
+    /** Candidate premise that matched this candidate (set for premise-based matches). */
+    candidatePremiseId?: Id<'premises'>;
+    /** Source context that produced this candidate (set when discoverySource is 'context-to-intent'). */
+    sourceContextId?: string;
+    networkId: Id<'networks'>;
+    similarity: number;
+    /** Free-text lens label that produced this match. */
+    lens: string;
+    candidatePayload: string;
+    candidateSummary?: string;
+    /** How this candidate was found: 'query' (HyDE from search text), 'premise-similarity', or 'context-to-intent'. */
+    discoverySource?: 'query' | 'premise-similarity' | 'context-to-intent';
+    /** Which discovery strategies found this candidate (set by mergeStrategyCandidates). */
+    matchedStrategies?: string[];
+    /** Typed evidence that explains why this candidate entered evaluation. */
+    evidence?: OpportunityEvidence[];
+}
+/**
+ * Evaluated candidate with LLM scoring (legacy; used when evaluator returns source/candidate pair).
+ * candidateIntentId is set for intent matches; omitted for profile-only matches.
+ */
+export interface EvaluatedCandidate {
+    sourceUserId: Id<'users'>;
+    candidateUserId: Id<'users'>;
+    sourceIntentId?: Id<'intents'>;
+    candidateIntentId?: Id<'intents'>;
+    networkId: Id<'networks'>;
+    score: number;
+    reasoning: string;
+    valencyRole: 'Agent' | 'Patient' | 'Peer';
+    /** Free-text lens label that produced this match. */
+    lens: string;
+}
+/**
+ * Actor in an evaluated opportunity (from entity-bundle evaluator).
+ * networkId is filled from the entity bundle in the graph, not by the evaluator.
+ */
+export interface EvaluatedOpportunityActor {
+    userId: Id<'users'>;
+    role: 'agent' | 'patient' | 'peer';
+    intentId?: Id<'intents'>;
+    networkId: Id<'networks'>;
+}
+/**
+ * Evaluated opportunity with multi-actor output (entity-bundle evaluator).
+ */
+export interface EvaluatedOpportunity {
+    actors: EvaluatedOpportunityActor[];
+    score: number;
+    reasoning: string;
+    evidence?: OpportunityEvidence[];
+}
+export interface OpportunityPersistenceOutcome {
+    evaluatedCount: number;
+    createdCount: number;
+    reactivatedCount: number;
+    sameTriggerDuplicateSuppressions: number;
+    pairActiveNegotiationSuppressions: number;
+    crossTriggerAllowedCount: number;
+    finalAtomicConflictCount: number;
+}
+/**
+ * Which flow triggered this graph invocation. Determines initial persist status,
+ * park-window timeout, streaming behavior, and whether AbortSignal is honored.
+ *
+ * - 'ambient' (default): queue-driven. Persists at the trigger default of
+ *   `pending` unless `options.initialStatus` overrides (the queue worker
+ *   passes `'latent'`, chat-bound ambient discovery passes `'draft'`). 5-min
+ *   park window, no streaming, ignores abort.
+ * - 'orchestrator': chat-driven. Persists at the trigger default of
+ *   `negotiating` unless `options.initialStatus` overrides. 60s park window,
+ *   streams `opportunity_draft_ready` events, honors abort.
+ *
+ * See {@link resolveInitialStatus} for the exact fallback used when
+ * `options.initialStatus` is undefined.
+ */
+export type OpportunityTrigger = 'ambient' | 'orchestrator';
+/**
+ * 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 declare function resolveInitialStatus(trigger: OpportunityTrigger, explicit: OpportunityStatus | undefined): OpportunityStatus;
+/**
+ * Options passed to the graph
+ */
+export interface OpportunityGraphOptions {
+    /** Exact durable ask_user settlement being resumed; internal queue path only. */
+    negotiationContinuation?: NegotiationContinuationExecution;
+    /** Initial status for created opportunities (default: 'pending') */
+    initialStatus?: OpportunityStatus;
+    /** Minimum score threshold (default: 50) */
+    minScore?: number;
+    /** Maximum opportunities to return (default: 20) */
+    limit?: number;
+    /** Pre-inferred lenses (if not provided, lens inference runs automatically in HyDE graph) */
+    lenses?: Lens[];
+    /** User's search query for HyDE generation */
+    hydeDescription?: string;
+    /** Existing opportunities summary for evaluator deduplication */
+    existingOpportunities?: string;
+    /** Chat session ID for draft opportunities; stored as context.conversationId for visibility filtering. */
+    conversationId?: string;
+    /**
+     * MCP-only: cap the negotiate-phase wall-clock at this many milliseconds.
+     * When set, `negotiateNode` races `negotiateCandidates(...)` against a timer;
+     * if the timer wins, the node returns early with a `timed_out` trace and the
+     * unawaited negotiation chains finalize each opp's DB status in the
+     * background. Set to 20_000 by the MCP `discover_opportunities` handler.
+     * Chat, ambient queue, and all other callers omit this — existing behavior.
+     */
+    negotiateTimeoutMs?: number;
+}
+/**
+ * Opportunity Graph State Annotation
+ */
+export declare const OpportunityGraphState: import("@langchain/langgraph").AnnotationRoot<{
+    userId: import("@langchain/langgraph").BaseChannel<Id<"users">, Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users">>, unknown>;
+    searchQuery: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    networkId: import("@langchain/langgraph").BaseChannel<Id<"networks"> | undefined, Id<"networks"> | import("@langchain/langgraph").OverwriteValue<Id<"networks"> | undefined> | undefined, unknown>;
+    /**
+     * 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: import("@langchain/langgraph").BaseChannel<Id<"networks">[] | undefined, Id<"networks">[] | import("@langchain/langgraph").OverwriteValue<Id<"networks">[] | undefined> | undefined, unknown>;
+    /** Optional intent to use as discovery source and for triggeredBy. When set, used for search text (if query empty) and persist. */
+    triggerIntentId: import("@langchain/langgraph").BaseChannel<Id<"intents"> | undefined, Id<"intents"> | import("@langchain/langgraph").OverwriteValue<Id<"intents"> | undefined> | undefined, unknown>;
+    /** Optional: restrict discovery to this specific user ID only (direct connection). */
+    targetUserId: import("@langchain/langgraph").BaseChannel<Id<"users"> | undefined, Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users"> | undefined> | undefined, unknown>;
+    /** Optional: discover on behalf of this user (introducer flow). When set, prep/eval use this user's profile/intents; userId becomes the introducer. */
+    onBehalfOfUserId: import("@langchain/langgraph").BaseChannel<Id<"users"> | undefined, Id<"users"> | import("@langchain/langgraph").OverwriteValue<Id<"users"> | undefined> | undefined, unknown>;
+    options: import("@langchain/langgraph").BaseChannel<OpportunityGraphOptions, OpportunityGraphOptions | import("@langchain/langgraph").OverwriteValue<OpportunityGraphOptions>, unknown>;
+    /**
+     * 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: import("@langchain/langgraph").BaseChannel<OpportunityTrigger, OpportunityTrigger | import("@langchain/langgraph").OverwriteValue<OpportunityTrigger>, unknown>;
+    /**
+     * 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: import("@langchain/langgraph").BaseChannel<{
+        opportunityId: string;
+        counterpartyUserId: string;
+    }[], {
+        opportunityId: string;
+        counterpartyUserId: string;
+    }[] | import("@langchain/langgraph").OverwriteValue<{
+        opportunityId: string;
+        counterpartyUserId: string;
+    }[]>, unknown>;
+    /**
+     * 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: import("@langchain/langgraph").BaseChannel<"delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing", "delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing" | import("@langchain/langgraph").OverwriteValue<"delete" | "send" | "update" | "approve_introduction" | "create" | "create_introduction" | "continue_discovery" | "read" | "negotiate_existing">, unknown>;
+    /** Introduction mode: pre-gathered entities (profiles + intents per party). */
+    introductionEntities: import("@langchain/langgraph").BaseChannel<EvaluatorEntity[], EvaluatorEntity[] | import("@langchain/langgraph").OverwriteValue<EvaluatorEntity[]>, unknown>;
+    /** Introduction mode: optional hint from the introducer. */
+    introductionHint: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    /** When set (e.g. chat scope), networkId must match this. */
+    requiredNetworkId: import("@langchain/langgraph").BaseChannel<Id<"networks"> | undefined, Id<"networks"> | import("@langchain/langgraph").OverwriteValue<Id<"networks"> | undefined> | undefined, unknown>;
+    /** Set by intro_evaluation; used by persist to build manual detection and introducer actor. */
+    introductionContext: import("@langchain/langgraph").BaseChannel<{
+        createdByName?: string;
+    } | undefined, {
+        createdByName?: string;
+    } | import("@langchain/langgraph").OverwriteValue<{
+        createdByName?: string;
+    } | undefined> | undefined, unknown>;
+    /** Target opportunity ID for update/delete/send modes. */
+    opportunityId: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    /** New status for update mode (e.g. 'accepted', 'rejected'). */
+    newStatus: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    /** User's indexed intents with hyde documents (from prep) */
+    indexedIntents: import("@langchain/langgraph").BaseChannel<IndexedIntent[], IndexedIntent[] | import("@langchain/langgraph").OverwriteValue<IndexedIntent[]>, unknown>;
+    /** User's network memberships (from prep) */
+    userNetworks: import("@langchain/langgraph").BaseChannel<Id<"networks">[], Id<"networks">[] | import("@langchain/langgraph").OverwriteValue<Id<"networks">[]>, unknown>;
+    /** Target indexes to search within (from scope) */
+    targetNetworks: import("@langchain/langgraph").BaseChannel<TargetNetwork[], TargetNetwork[] | import("@langchain/langgraph").OverwriteValue<TargetNetwork[]>, unknown>;
+    /** Per-index relevancy scores for dedup tie-breaking. Background path: from intent_indexes. Chat path: transient from IntentIndexer. */
+    indexRelevancyScores: import("@langchain/langgraph").BaseChannel<Record<string, number>, Record<string, number> | import("@langchain/langgraph").OverwriteValue<Record<string, number>>, unknown>;
+    /** 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: import("@langchain/langgraph").BaseChannel<"intent" | "context", "intent" | "context" | import("@langchain/langgraph").OverwriteValue<"intent" | "context">, unknown>;
+    /** Resolved intent ID used for this discovery run (when discoverySource is 'intent'). Set by intent-resolution. */
+    resolvedTriggerIntentId: import("@langchain/langgraph").BaseChannel<Id<"intents"> | undefined, Id<"intents"> | import("@langchain/langgraph").OverwriteValue<Id<"intents"> | undefined> | undefined, unknown>;
+    /** Asker's profile (from prep). Used for profile-as-source discovery and evaluation. */
+    sourceProfile: import("@langchain/langgraph").BaseChannel<SourceProfileData | null, SourceProfileData | import("@langchain/langgraph").OverwriteValue<SourceProfileData | null> | null, unknown>;
+    /** User's active premises with embeddings (from prep). Used for premise-to-premise discovery path D. */
+    sourcePremises: import("@langchain/langgraph").BaseChannel<{
+        premiseId: Id<"premises">;
+        embedding: number[];
+    }[], {
+        premiseId: Id<"premises">;
+        embedding: number[];
+    }[] | import("@langchain/langgraph").OverwriteValue<{
+        premiseId: Id<"premises">;
+        embedding: number[];
+    }[]>, unknown>;
+    /** User context embeddings per network (from prep). Used for context-to-intent discovery. */
+    sourceContexts: import("@langchain/langgraph").BaseChannel<{
+        contextId: string;
+        networkId: Id<"networks">;
+        text: string;
+        embedding: number[];
+    }[], {
+        contextId: string;
+        networkId: Id<"networks">;
+        text: string;
+        embedding: number[];
+    }[] | import("@langchain/langgraph").OverwriteValue<{
+        contextId: string;
+        networkId: Id<"networks">;
+        text: string;
+        embedding: number[];
+    }[]>, unknown>;
+    /** Resolved intent is in at least one target index (path A vs C). */
+    resolvedIntentInIndex: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
+    /** Create-intent signal: when true, tool should return createIntentSuggested so agent can auto-call create_intent. */
+    createIntentSuggested: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
+    /** Suggested description for create_intent when createIntentSuggested is true. */
+    suggestedIntentDescription: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    /** HyDE embeddings per lens label (from discovery) */
+    hydeEmbeddings: import("@langchain/langgraph").BaseChannel<Record<string, number[]>, Record<string, number[]> | import("@langchain/langgraph").OverwriteValue<Record<string, number[]>>, unknown>;
+    /** Candidate matches from semantic search (from discovery) */
+    candidates: import("@langchain/langgraph").BaseChannel<CandidateMatch[], CandidateMatch[] | import("@langchain/langgraph").OverwriteValue<CandidateMatch[]>, unknown>;
+    /** Candidates not yet evaluated (for pagination -- cached in Redis by caller). */
+    remainingCandidates: import("@langchain/langgraph").BaseChannel<CandidateMatch[], CandidateMatch[] | import("@langchain/langgraph").OverwriteValue<CandidateMatch[]>, unknown>;
+    /** Discovery session ID for pagination (maps to Redis cache key). */
+    discoveryId: import("@langchain/langgraph").BaseChannel<string | null, string | import("@langchain/langgraph").OverwriteValue<string | null> | null, unknown>;
+    /** Evaluated candidates with scores (from evaluation; legacy) */
+    evaluatedCandidates: import("@langchain/langgraph").BaseChannel<EvaluatedCandidate[], EvaluatedCandidate[] | import("@langchain/langgraph").OverwriteValue<EvaluatedCandidate[]>, unknown>;
+    /** Evaluated opportunities with actors (from entity-bundle evaluator) */
+    evaluatedOpportunities: import("@langchain/langgraph").BaseChannel<EvaluatedOpportunity[], EvaluatedOpportunity[] | import("@langchain/langgraph").OverwriteValue<EvaluatedOpportunity[]>, unknown>;
+    /** Final ranked and persisted opportunities */
+    opportunities: import("@langchain/langgraph").BaseChannel<Opportunity[], Opportunity[] | import("@langchain/langgraph").OverwriteValue<Opportunity[]>, unknown>;
+    /** Discovery path: pairs skipped because an opportunity already exists between viewer and candidate (no duplicate created). */
+    existingBetweenActors: import("@langchain/langgraph").BaseChannel<{
+        candidateUserId: Id<"users">;
+        networkId: Id<"networks">;
+        existingOpportunityId?: Id<"opportunities">;
+        existingStatus?: OpportunityStatus;
+        reason?: "same_trigger_recent_duplicate" | "pair_active_negotiation" | "final_atomic_conflict";
+        existingTriggerIntentId?: string;
+    }[], {
+        candidateUserId: Id<"users">;
+        networkId: Id<"networks">;
+        existingOpportunityId?: Id<"opportunities">;
+        existingStatus?: OpportunityStatus;
+        reason?: "same_trigger_recent_duplicate" | "pair_active_negotiation" | "final_atomic_conflict";
+        existingTriggerIntentId?: string;
+    }[] | import("@langchain/langgraph").OverwriteValue<{
+        candidateUserId: Id<"users">;
+        networkId: Id<"networks">;
+        existingOpportunityId?: Id<"opportunities">;
+        existingStatus?: OpportunityStatus;
+        reason?: "same_trigger_recent_duplicate" | "pair_active_negotiation" | "final_atomic_conflict";
+        existingTriggerIntentId?: string;
+    }[]>, unknown>;
+    /** Typed persist-node counts used by queue telemetry. */
+    persistenceOutcome: import("@langchain/langgraph").BaseChannel<OpportunityPersistenceOutcome | undefined, OpportunityPersistenceOutcome | import("@langchain/langgraph").OverwriteValue<OpportunityPersistenceOutcome | undefined> | undefined, unknown>;
+    /** Positive exact-successor receipt for a fenced continuation. */
+    negotiationContinuationReceipt: import("@langchain/langgraph").BaseChannel<NegotiationContinuationReceipt | undefined, NegotiationContinuationReceipt | import("@langchain/langgraph").OverwriteValue<NegotiationContinuationReceipt | undefined> | undefined, unknown>;
+    /** Error message if any step fails */
+    error: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    /** Output for read mode: enriched list of opportunities. */
+    readResult: import("@langchain/langgraph").BaseChannel<{
+        count: number;
+        message?: string;
+        opportunities: Array<{
+            id: string;
+            indexName: string;
+            connectedWith: string[];
+            suggestedBy: string | null;
+            reasoning: string;
+            status: string;
+            category: string;
+            confidence: number | null;
+            source: string | null;
+        }>;
+    } | undefined, {
+        count: number;
+        message?: string;
+        opportunities: Array<{
+            id: string;
+            indexName: string;
+            connectedWith: string[];
+            suggestedBy: string | null;
+            reasoning: string;
+            status: string;
+            category: string;
+            confidence: number | null;
+            source: string | null;
+        }>;
+    } | import("@langchain/langgraph").OverwriteValue<{
+        count: number;
+        message?: string;
+        opportunities: Array<{
+            id: string;
+            indexName: string;
+            connectedWith: string[];
+            suggestedBy: string | null;
+            reasoning: string;
+            status: string;
+            category: string;
+            confidence: number | null;
+            source: string | null;
+        }>;
+    } | undefined> | undefined, unknown>;
+    /** Output for update/delete/send modes. */
+    mutationResult: import("@langchain/langgraph").BaseChannel<{
+        success: boolean;
+        message?: string;
+        opportunityId?: string;
+        notified?: string[];
+        conversationId?: string;
+        error?: string;
+    } | undefined, {
+        success: boolean;
+        message?: string;
+        opportunityId?: string;
+        notified?: string[];
+        conversationId?: string;
+        error?: string;
+    } | import("@langchain/langgraph").OverwriteValue<{
+        success: boolean;
+        message?: string;
+        opportunityId?: string;
+        notified?: string[];
+        conversationId?: string;
+        error?: string;
+    } | undefined> | undefined, unknown>;
+    /**
+     * 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: import("@langchain/langgraph").BaseChannel<{
+        node: string;
+        detail?: string;
+        data?: Record<string, unknown>;
+    }[], {
+        node: string;
+        detail?: string;
+        data?: Record<string, unknown>;
+    }[] | import("@langchain/langgraph").OverwriteValue<{
+        node: string;
+        detail?: string;
+        data?: Record<string, unknown>;
+    }[]>, unknown>;
+    /** Timing records for each agent invocation within this graph run. */
+    agentTimings: import("@langchain/langgraph").BaseChannel<DebugMetaAgent[], DebugMetaAgent[] | import("@langchain/langgraph").OverwriteValue<DebugMetaAgent[]>, unknown>;
+    /**
+     * 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: import("@langchain/langgraph").BaseChannel<{
+        counterpartyHint: string;
+        indexContext: string;
+        counterpartyId: string;
+        turns: {
+            reasoning: string;
+            suggestedRoles: {
+                ownUser: "agent" | "patient" | "peer";
+                otherUser: "agent" | "patient" | "peer";
+            };
+            action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
+        }[];
+        outcome: {
+            reasoning: string;
+            hasOpportunity: boolean;
+            reason?: "timeout" | "turn_cap" | "screened_out" | undefined;
+            agreedRoles?: {
+                userId: string;
+                role: "agent" | "patient" | "peer";
+            }[] | undefined;
+        };
+        seedAssessmentScore?: number | undefined;
+    }[], {
+        counterpartyHint: string;
+        indexContext: string;
+        counterpartyId: string;
+        turns: {
+            reasoning: string;
+            suggestedRoles: {
+                ownUser: "agent" | "patient" | "peer";
+                otherUser: "agent" | "patient" | "peer";
+            };
+            action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
+        }[];
+        outcome: {
+            reasoning: string;
+            hasOpportunity: boolean;
+            reason?: "timeout" | "turn_cap" | "screened_out" | undefined;
+            agreedRoles?: {
+                userId: string;
+                role: "agent" | "patient" | "peer";
+            }[] | undefined;
+        };
+        seedAssessmentScore?: number | undefined;
+    }[] | import("@langchain/langgraph").OverwriteValue<{
+        counterpartyHint: string;
+        indexContext: string;
+        counterpartyId: string;
+        turns: {
+            reasoning: string;
+            suggestedRoles: {
+                ownUser: "agent" | "patient" | "peer";
+                otherUser: "agent" | "patient" | "peer";
+            };
+            action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
+        }[];
+        outcome: {
+            reasoning: string;
+            hasOpportunity: boolean;
+            reason?: "timeout" | "turn_cap" | "screened_out" | undefined;
+            agreedRoles?: {
+                userId: string;
+                role: "agent" | "patient" | "peer";
+            }[] | undefined;
+        };
+        seedAssessmentScore?: number | undefined;
+    }[]>, unknown>;
+    /** Aggregate counters across `discoveryNegotiations`. Built in the negotiate node. */
+    discoverySummary: import("@langchain/langgraph").BaseChannel<DiscoverySummary | null, DiscoverySummary | import("@langchain/langgraph").OverwriteValue<DiscoverySummary | null> | null, unknown>;
+}>;