@indexnetwork/protocol 6.12.1-rc.404.1 → 6.13.22-rc.405.1

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

@@ -0,0 +1,58 @@
+/**
+ * Shared persist phase for opportunity creation: enrichOrCreate → create (or create+expire) → optional chat injection.
+ * Used by the opportunity graph persist node and by the manual opportunity service for consistency.
+ */
+import type { CreateOpportunityData, IntentScopedOpportunityPersistenceResult, Opportunity, OpportunityDedupConflict, OpportunityNetworkEligibility, OpportunityStatus } from '../../shared/interfaces/database.interface.js';
+import type { Embedder } from '../../shared/interfaces/embedder.interface.js';
+import type { EnricherDatabase } from './opportunity.enricher.js';
+export type PersistOpportunityDatabase = EnricherDatabase & {
+    createOpportunity(data: CreateOpportunityData): Promise<Opportunity>;
+    createOpportunityIfNetworkEligible?(data: CreateOpportunityData, eligibility: OpportunityNetworkEligibility): Promise<Opportunity | null>;
+    updateOpportunityStatus(id: string, status: OpportunityStatus): Promise<void | Opportunity | null>;
+    createOpportunityAndExpireIds?(data: CreateOpportunityData, expireIds: string[]): Promise<{
+        created: Opportunity;
+        expired: Opportunity[];
+    }>;
+    createOpportunityAndExpireIdsIfNetworkEligible?(data: CreateOpportunityData, expireIds: string[], eligibility: OpportunityNetworkEligibility): Promise<{
+        created: Opportunity;
+        expired: Opportunity[];
+    } | null>;
+    persistIntentScopedOpportunityIfNetworkEligible?(data: CreateOpportunityData, expireIds: string[], eligibility: OpportunityNetworkEligibility & {
+        triggerIntentId: string;
+    }, dedupWindowMs: number): Promise<IntentScopedOpportunityPersistenceResult | null>;
+    /** Optional: used to populate expired list in non-atomic path. */
+    getOpportunity?(id: string): Promise<Opportunity | null>;
+};
+export interface PersistOpportunitiesParams {
+    database: PersistOpportunityDatabase;
+    embedder: Embedder;
+    items: CreateOpportunityData[];
+    injectChat?: (opportunity: Opportunity) => Promise<unknown>;
+    /** Require adapter-level membership/assignment locks for discovery-created rows. */
+    networkEligibility?: OpportunityNetworkEligibility;
+    /** Scope dedup/enrichment and the final atomic re-check to one owned intent. */
+    intentDedupScope?: {
+        triggerIntentId: string;
+        dedupWindowMs: number;
+    };
+}
+export interface PersistOpportunitiesError {
+    itemIndex: number;
+    error: unknown;
+}
+export interface PersistOpportunitiesConflict extends OpportunityDedupConflict {
+    itemIndex: number;
+    finalAtomic: true;
+}
+export interface PersistOpportunitiesResult {
+    created: Opportunity[];
+    expired: Opportunity[];
+    conflicts: PersistOpportunitiesConflict[];
+    errors?: PersistOpportunitiesError[];
+}
+/**
+ * Persist one or more opportunities: enrich (merge overlapping), create, expire replaced, optional chat injection.
+ * When the database has createOpportunityAndExpireIds and enrichment produced expireIds, uses it for atomic create+expire.
+ * Returns both created and expired so callers can emit events (e.g. manual service).
+ */
+export declare function persistOpportunities(params: PersistOpportunitiesParams): Promise<PersistOpportunitiesResult>;

package/dist/opportunity/application/opportunity.persist.js

@@ -0,0 +1,145 @@
+/**
+ * Shared persist phase for opportunity creation: enrichOrCreate → create (or create+expire) → optional chat injection.
+ * Used by the opportunity graph persist node and by the manual opportunity service for consistency.
+ */
+import { enrichOrCreate } from './opportunity.enricher.js';
+import { normalizeCreateOpportunityActorIntents } from '../domain/opportunity.actor.js';
+import { protocolLogger } from '../../shared/observability/protocol.logger.js';
+const logger = protocolLogger('OpportunityPersist');
+/** Bind owned-intent discovery actors to the already-authorized trigger intent. */
+function bindOwnedIntentActors(data, ownerUserId, triggerIntentId) {
+    const actors = [];
+    const boundActorIndexes = new Map();
+    for (const actor of data.actors) {
+        if (actor.userId !== ownerUserId || actor.role === 'introducer') {
+            actors.push(actor);
+            continue;
+        }
+        const boundActor = {
+            ...actor,
+            intent: triggerIntentId,
+        };
+        const key = JSON.stringify([boundActor.networkId, boundActor.userId, triggerIntentId]);
+        const existingIndex = boundActorIndexes.get(key);
+        if (existingIndex === undefined) {
+            boundActorIndexes.set(key, actors.length);
+            actors.push(boundActor);
+        }
+        else {
+            actors[existingIndex] = boundActor;
+        }
+    }
+    return { ...data, actors };
+}
+/**
+ * Persist one or more opportunities: enrich (merge overlapping), create, expire replaced, optional chat injection.
+ * When the database has createOpportunityAndExpireIds and enrichment produced expireIds, uses it for atomic create+expire.
+ * Returns both created and expired so callers can emit events (e.g. manual service).
+ */
+export async function persistOpportunities(params) {
+    const { database, embedder, items, injectChat, networkEligibility, intentDedupScope } = params;
+    const created = [];
+    const expired = [];
+    const conflicts = [];
+    const errors = [];
+    for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+        const data = items[itemIndex];
+        try {
+            const normalizedData = normalizeCreateOpportunityActorIntents(data);
+            if (intentDedupScope
+                && intentDedupScope.triggerIntentId !== networkEligibility?.triggerIntentId) {
+                throw new Error('Intent-scoped dedup trigger must match network eligibility');
+            }
+            const scopedData = intentDedupScope && networkEligibility
+                ? bindOwnedIntentActors(normalizedData, networkEligibility.ownerUserId, intentDedupScope.triggerIntentId)
+                : normalizedData;
+            const enrichment = await enrichOrCreate(database, embedder, scopedData, intentDedupScope && networkEligibility
+                ? {
+                    ownedIntentScope: {
+                        triggerIntentId: intentDedupScope.triggerIntentId,
+                        ownerUserId: networkEligibility.ownerUserId,
+                    },
+                }
+                : undefined);
+            const normalizedToCreate = normalizeCreateOpportunityActorIntents(enrichment.data);
+            const toCreate = intentDedupScope && networkEligibility
+                ? bindOwnedIntentActors(normalizedToCreate, networkEligibility.ownerUserId, intentDedupScope.triggerIntentId)
+                : normalizedToCreate;
+            if (enrichment.enriched) {
+                toCreate.status = enrichment.resolvedStatus;
+            }
+            if (intentDedupScope) {
+                if (!networkEligibility?.triggerIntentId) {
+                    throw new Error('Intent-scoped dedup requires trigger-intent network eligibility');
+                }
+                if (!database.persistIntentScopedOpportunityIfNetworkEligible) {
+                    throw new Error('Intent-scoped atomic persistence is required for owned-intent discovery');
+                }
+                const result = await database.persistIntentScopedOpportunityIfNetworkEligible(toCreate, enrichment.enriched ? enrichment.expiredIds : [], { ...networkEligibility, triggerIntentId: networkEligibility.triggerIntentId }, intentDedupScope.dedupWindowMs);
+                if (!result)
+                    continue;
+                if ('conflict' in result) {
+                    conflicts.push({ itemIndex, finalAtomic: true, ...result.conflict });
+                    continue;
+                }
+                created.push(result.created);
+                expired.push(...result.expired);
+            }
+            else if (networkEligibility) {
+                if (enrichment.enriched && enrichment.expiredIds.length > 0) {
+                    if (!database.createOpportunityAndExpireIdsIfNetworkEligible) {
+                        throw new Error('Network-eligible create+expire is required for discovery persistence');
+                    }
+                    const result = await database.createOpportunityAndExpireIdsIfNetworkEligible(toCreate, enrichment.expiredIds, networkEligibility);
+                    if (!result)
+                        continue;
+                    created.push(result.created);
+                    expired.push(...result.expired);
+                }
+                else {
+                    if (!database.createOpportunityIfNetworkEligible) {
+                        throw new Error('Network-eligible create is required for discovery persistence');
+                    }
+                    const c = await database.createOpportunityIfNetworkEligible(toCreate, networkEligibility);
+                    if (!c)
+                        continue;
+                    created.push(c);
+                }
+            }
+            else if (database.createOpportunityAndExpireIds &&
+                enrichment.enriched &&
+                enrichment.expiredIds.length > 0) {
+                const result = await database.createOpportunityAndExpireIds(toCreate, enrichment.expiredIds);
+                created.push(result.created);
+                expired.push(...result.expired);
+            }
+            else {
+                const c = await database.createOpportunity(toCreate);
+                created.push(c);
+                if (enrichment.enriched && enrichment.expiredIds.length > 0) {
+                    for (const id of enrichment.expiredIds) {
+                        await database.updateOpportunityStatus(id, 'expired');
+                    }
+                    if (database.getOpportunity) {
+                        for (const id of enrichment.expiredIds) {
+                            const opp = await database.getOpportunity(id);
+                            if (opp)
+                                expired.push(opp);
+                        }
+                    }
+                }
+            }
+            const lastCreated = created[created.length - 1];
+            if (lastCreated?.status === 'pending' && injectChat) {
+                await injectChat(lastCreated).catch((err) => {
+                    logger.warn('Chat injection failed', { opportunityId: lastCreated.id, error: err });
+                });
+            }
+        }
+        catch (err) {
+            errors.push({ itemIndex, error: err });
+            logger.warn('Item failed', { itemIndex, error: err });
+        }
+    }
+    return { created, expired, conflicts, ...(errors.length > 0 ? { errors } : {}) };
+}

package/dist/opportunity/application/opportunity.persistence-admission.d.ts

@@ -0,0 +1,39 @@
+import type { Id, Opportunity, OpportunityActor, OpportunityGraphDatabase, OpportunityNetworkEligibility } from '../../shared/interfaces/database.interface.js';
+/** Narrow final-boundary port for opportunity persistence admission and guarded reactivation. */
+export type OpportunityPersistenceAdmissionPort = Pick<OpportunityGraphDatabase, 'getActiveNetworkMembershipPairs' | 'getNetworkIdsForIntent' | 'getNetworkMemberships' | 'updateOpportunityStatusIfNetworkEligible'>;
+type EvaluatedPersistenceCandidate = {
+    actors: Array<{
+        userId: Id<'users'>;
+        networkId?: Id<'networks'> | null;
+    }>;
+};
+export interface OpportunityPersistenceAdmissionInput<T extends EvaluatedPersistenceCandidate> {
+    ownerUserId: Id<'users'>;
+    triggerIntentId?: Id<'intents'>;
+    networkId?: Id<'networks'>;
+    indexScope?: readonly Id<'networks'>[];
+    evaluatedOpportunities: readonly T[];
+}
+export type OpportunityPersistenceAdmission<T extends EvaluatedPersistenceCandidate> = {
+    kind: 'empty_scope';
+} | {
+    kind: 'admitted';
+    allowedNetworkIds: Id<'networks'>[];
+    networkEligibility: OpportunityNetworkEligibility;
+    evaluatedOpportunities: T[];
+};
+/**
+ * Recomputes the owner-side scope at the final write boundary and removes
+ * evaluator outputs whose actor/network anchors are no longer active.
+ */
+export declare function admitOpportunityPersistence<T extends EvaluatedPersistenceCandidate>(database: OpportunityPersistenceAdmissionPort, input: OpportunityPersistenceAdmissionInput<T>): Promise<OpportunityPersistenceAdmission<T>>;
+export interface EligibleStatusUpdateObserver {
+    onUnavailableAdapter?: () => void;
+}
+/**
+ * Produces the guarded status-update handler used when dedup reactivates an
+ * existing row. Existing non-introducer actor anchors are rechecked in the
+ * same adapter operation as the status transition.
+ */
+export declare function createEligibleOpportunityStatusUpdater(database: OpportunityPersistenceAdmissionPort, allowedNetworkIds: readonly Id<'networks'>[], networkEligibility: OpportunityNetworkEligibility, observer?: EligibleStatusUpdateObserver): (opportunityId: string, status: Opportunity['status'], existingActors: OpportunityActor[], expectedStatus: Opportunity['status']) => Promise<Opportunity | null>;
+export {};

package/dist/opportunity/application/opportunity.persistence-admission.js

@@ -0,0 +1,59 @@
+/**
+ * Recomputes the owner-side scope at the final write boundary and removes
+ * evaluator outputs whose actor/network anchors are no longer active.
+ */
+export async function admitOpportunityPersistence(database, input) {
+    const memberships = await database.getNetworkMemberships(input.ownerUserId);
+    let allowedNetworkIds = memberships.map((membership) => membership.networkId);
+    if (input.triggerIntentId) {
+        const assignments = new Set(await database.getNetworkIdsForIntent(input.triggerIntentId));
+        allowedNetworkIds = allowedNetworkIds.filter((networkId) => assignments.has(networkId));
+    }
+    const explicitScope = input.networkId ? [input.networkId] : input.indexScope;
+    if (explicitScope !== undefined) {
+        const explicitlyAllowed = new Set(explicitScope);
+        allowedNetworkIds = allowedNetworkIds.filter((networkId) => explicitlyAllowed.has(networkId));
+    }
+    allowedNetworkIds = [...new Set(allowedNetworkIds)];
+    if (allowedNetworkIds.length === 0)
+        return { kind: 'empty_scope' };
+    const allowedNetworks = new Set(allowedNetworkIds);
+    const requestedPairs = input.evaluatedOpportunities.flatMap((evaluated) => evaluated.actors.flatMap((actor) => actor.networkId
+        ? [{ userId: actor.userId, networkId: actor.networkId }]
+        : []));
+    const activePairs = await database.getActiveNetworkMembershipPairs(requestedPairs);
+    const activePairKeys = new Set(activePairs.map((pair) => `${pair.userId}\u0000${pair.networkId}`));
+    const evaluatedOpportunities = input.evaluatedOpportunities.filter((evaluated) => evaluated.actors.length > 0
+        && evaluated.actors.every((actor) => actor.networkId != null
+            && allowedNetworks.has(actor.networkId)
+            && activePairKeys.has(`${actor.userId}\u0000${actor.networkId}`)));
+    return {
+        kind: 'admitted',
+        allowedNetworkIds,
+        networkEligibility: {
+            ownerUserId: input.ownerUserId,
+            allowedNetworkIds,
+            ...(input.triggerIntentId ? { triggerIntentId: input.triggerIntentId } : {}),
+        },
+        evaluatedOpportunities,
+    };
+}
+/**
+ * Produces the guarded status-update handler used when dedup reactivates an
+ * existing row. Existing non-introducer actor anchors are rechecked in the
+ * same adapter operation as the status transition.
+ */
+export function createEligibleOpportunityStatusUpdater(database, allowedNetworkIds, networkEligibility, observer) {
+    const allowedNetworks = new Set(allowedNetworkIds);
+    return async (opportunityId, status, existingActors, expectedStatus) => {
+        const anchors = existingActors.filter((actor) => actor.role !== 'introducer');
+        if (anchors.length === 0 || anchors.some((actor) => !allowedNetworks.has(actor.networkId))) {
+            return null;
+        }
+        if (!database.updateOpportunityStatusIfNetworkEligible) {
+            observer?.onUnavailableAdapter?.();
+            return null;
+        }
+        return database.updateOpportunityStatusIfNetworkEligible(opportunityId, status, anchors, networkEligibility, expectedStatus);
+    };
+}

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

@@ -0,0 +1,156 @@
+/**
+ * Opportunity Presenter Agent
+ *
+ * Generates personalized, second-person explanations of why an opportunity
+ * matters to the viewing user. Uses full opportunity data (interpretation,
+ * actors, profiles, intents, index) to produce headline, personalizedSummary,
+ * and suggestedAction for chat tools and user-facing surfaces.
+ */
+import { z } from "zod";
+import type { Opportunity } from "../../shared/interfaces/database.interface.js";
+import type { ChatGraphCompositeDatabase } from "../../shared/interfaces/database.interface.js";
+import type { NegotiationContext } from "./negotiation-context.loader.js";
+/**
+ * Minimal database interface required by gatherPresenterContext.
+ * Any database adapter that implements these three methods can be passed.
+ */
+export type PresenterDatabase = Pick<ChatGraphCompositeDatabase, "getProfile" | "getActiveIntents" | "getNetwork" | "getPremisesForUser">;
+declare const PresentationSchema: z.ZodObject<{
+    headline: z.ZodString;
+    personalizedSummary: z.ZodString;
+    suggestedAction: z.ZodString;
+    greeting: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    headline: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+    greeting: string;
+}, {
+    headline: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+    greeting: string;
+}>;
+export type OpportunityPresentationResult = z.infer<typeof PresentationSchema> & {
+    /** True when any output field used resilience fallback copy. */
+    isFallback?: boolean;
+    /** Diagnostic category; never changes production fallback policy. */
+    fallbackReason?: "timeout" | "error" | "sanitization";
+};
+/** Input for home-card presenter call; extends PresenterInput with optional mutual intent count. */
+export interface HomeCardPresenterInput extends PresenterInput {
+    /** Number of overlapping intents (for generating mutualIntentsLabel). */
+    mutualIntentCount?: number;
+    /**
+     * Snapshot of the opportunity's negotiation, if one exists. When status is
+     * `negotiating`, the presenter returns a templated chip without invoking
+     * the LLM. For `pending`/`stalled`/`accepted`/`rejected`, the full
+     * transcript and outcome ground the LLM's explanation.
+     */
+    negotiationContext?: NegotiationContext;
+}
+/** LLM-generated fields for home-card presentation (buttons are hardcoded by callers, not LLM-generated). */
+export declare const HomeCardLLMSchema: z.ZodObject<{
+    headline: z.ZodString;
+    personalizedSummary: z.ZodString;
+    digestSummary: z.ZodString;
+    suggestedAction: z.ZodString;
+    narratorRemark: z.ZodString;
+    mutualIntentsLabel: z.ZodString;
+    greeting: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    headline: string;
+    mutualIntentsLabel: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+    greeting: string;
+    digestSummary: string;
+    narratorRemark: string;
+}, {
+    headline: string;
+    mutualIntentsLabel: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+    greeting: string;
+    digestSummary: string;
+    narratorRemark: string;
+}>;
+/** LLM-generated result from presentHomeCard (callers append button labels from opportunity.constants). */
+export type HomeCardLLMResult = z.infer<typeof HomeCardLLMSchema> & {
+    /**
+     * True when the LLM call failed and this is fallback-shaped copy built from
+     * raw match reasoning. Callers with strict quality requirements (digests,
+     * long-lived caches) should check this before sending/persisting — fallback
+     * output is otherwise indistinguishable from genuine LLM output.
+     */
+    isFallback?: boolean;
+};
+/** Full home-card display contract including hardcoded button labels (assembled by callers). */
+export type HomeCardPresentationResult = HomeCardLLMResult & {
+    primaryActionLabel: string;
+    secondaryActionLabel: string;
+};
+/** Input for a single presenter call (all context pre-assembled). */
+export interface PresenterInput {
+    viewerContext: string;
+    otherPartyContext: string;
+    matchReasoning: string;
+    category: string;
+    confidence: number;
+    signalsSummary: string;
+    indexName: string;
+    viewerRole: string;
+    opportunityStatus?: string;
+    /** True when this opportunity was created via an explicit introduction (not automatic discovery). */
+    isIntroduction?: boolean;
+    /** Name of the person who made the introduction, if applicable. */
+    introducerName?: string;
+}
+export declare class OpportunityPresenter {
+    private model;
+    private homeCardModel;
+    constructor();
+    private invokeWithTimeout;
+    /**
+     * Generate personalized presentation for a single opportunity.
+     */
+    present(input: PresenterInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<OpportunityPresentationResult>;
+    /**
+     * Generate LLM-powered home-card content (headline, body, narrator remark, mutual-intent label).
+     * Callers append button labels from opportunity.constants.
+     *
+     * When `negotiationContext.status === 'negotiating'`, returns a templated
+     * chip synchronously without invoking the LLM — the card just reflects
+     * "negotiation in progress" at that point.
+     */
+    presentHomeCard(input: HomeCardPresenterInput): Promise<HomeCardLLMResult>;
+    /**
+     * Process multiple opportunities in parallel with bounded concurrency.
+     */
+    presentBatch(inputs: PresenterInput[], options?: {
+        concurrency?: number;
+    }): Promise<OpportunityPresentationResult[]>;
+    /**
+     * Process multiple opportunities as home cards in parallel with bounded concurrency.
+     * Returns full home-card display contracts (headline, body, narrator remark, action labels, mutual-intent label).
+     */
+    presentHomeCardBatch(inputs: HomeCardPresenterInput[], options?: {
+        concurrency?: number;
+    }): Promise<HomeCardLLMResult[]>;
+}
+/**
+ * Build the LLM-facing signal summary while excluding pool adjustments. Pool
+ * disposition is rendered deterministically by the card chip; asking the
+ * presenter to interpret it could turn a demotion into a positive rationale.
+ */
+export declare function summarizeSignalsForPresenter(signals: Opportunity['interpretation']['signals']): string;
+/**
+ * Gather all context needed for the presenter from the database.
+ * Fetches viewer profile, viewer intents, other party profile(s), and index in parallel.
+ *
+ * @param displayCounterpartUserId - When set (e.g. for home card), only this counterpart is included in otherPartyContext so the presenter writes about the person on the card. Omitted for introducer view (card shows both parties).
+ */
+export declare function gatherPresenterContext(database: PresenterDatabase, opportunity: Opportunity, viewerId: string, displayCounterpartUserId?: string): Promise<PresenterInput>;
+export {};