@indexnetwork/protocol 22.0.0-rc.498.1 → 64.0.0-rc.604.2

package/dist/{opportunities → internal/opportunities}/opportunity.update-admission.d.ts

@@ -1,6 +1,6 @@
-import type { Opportunity, OpportunityGraphDatabase } from '../shared/interfaces/database.interface.js';
+import type { Opportunity, OpportunityDatabase } from '../../platform/database.js';
 /** Narrow persistence read port for authorizing a user-driven opportunity update. */
-export type OpportunityUpdateAdmissionPort = Pick<OpportunityGraphDatabase, 'getOpportunity'>;
+export type OpportunityUpdateAdmissionPort = Pick<OpportunityDatabase, 'getOpportunity'>;
 export interface OpportunityUpdateAdmissionInput {
     opportunityId: string;
     viewerId: string;

package/dist/internal/opportunities/opportunity.utils.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Validates opportunity actors.
+ *
+ * Rejects self-matches — the same person occupying both sides of a pairing.
+ * The evaluator's actor list can collapse onto a single user; downstream
+ * readers then garble identity (a greeting rendered in one party's voice while
+ * the card shows the viewer "matched with themselves"). Only `userId`-bearing
+ * actors are checked; role-only actors (tests) pass. Duplicate rows for one
+ * participant are allowed when at least one other distinct participant is
+ * present.
+ *
+ * @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.
+ *
+ * This used to be a four-way rule keyed on role, `latent`, and whether an
+ * a third party had vouched. None of that exists any
+ * more — an opportunity is born `negotiating` when a principal's agent opens
+ * it — so every branch collapsed to the same answer: the actors on a pairing
+ * may read it.
+ */
+export declare function canUserSeeOpportunity(actors: Array<{
+    userId: string;
+    role: string;
+}>, _status: string, userId: string): boolean;
+/**
+ * Whether an opportunity should appear on the viewer's radar (actionable =
+ * has a pending action for this user).
+ *
+ * Only `pending` is actionable, and only while the viewer has no `committed` event.
+ *
+ * The old rules 1-3 were about pre-kickoff states and vouching. Neither
+ * exists: a pairing is born `negotiating`, and a negotiating pairing is the
+ * agents' to work, not the principal's to action.
+ */
+export declare function isActionableForViewer(actors: Array<{
+    userId: string;
+    role: string;
+}>, status: string, viewerId: string, committedActorIds?: readonly string[]): boolean;
+/** Feed category for home composition. */
+export type FeedCategory = 'connection' | 'expired';
+/** Soft targets for radar composition. */
+export declare const RADAR_SOFT_TARGETS: {
+    readonly connection: 5;
+    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 - Unused; retained for call-site compatibility
+ * @returns Feed category
+ */
+export declare function classifyOpportunity(opp: {
+    actors: Array<{
+        userId: string;
+        role: string;
+    }>;
+    status: string;
+}, _viewerId: string): FeedCategory;
+/**
+ * Select opportunities for the radar 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.
+ * 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[];

package/dist/internal/opportunities/opportunity.utils.js

@@ -0,0 +1,165 @@
+import { log } from '../shared/observability/log.js';
+const logger = log.graph.from('SelectByComposition');
+const dedupeByPersonLog = log.graph.from('DeduplicateByPerson');
+/**
+ * Validates opportunity actors.
+ *
+ * Rejects self-matches — the same person occupying both sides of a pairing.
+ * The evaluator's actor list can collapse onto a single user; downstream
+ * readers then garble identity (a greeting rendered in one party's voice while
+ * the card shows the viewer "matched with themselves"). Only `userId`-bearing
+ * actors are checked; role-only actors (tests) pass. Duplicate rows for one
+ * participant are allowed when at least one other distinct participant is
+ * present.
+ *
+ * @param actors - Array of actors with at least a role and optional userId
+ * @throws Error when the actor set is invalid
+ */
+export function validateOpportunityActors(actors) {
+    const userIds = actors.filter((a) => a.userId).map((a) => a.userId);
+    if (userIds.length > 1 && new Set(userIds).size === 1) {
+        throw new Error('An opportunity cannot match a user with themselves (duplicate participant).');
+    }
+}
+/**
+ * Read-level ACL: whether a user is an actor on the opportunity and may fetch
+ * its details.
+ *
+ * This used to be a four-way rule keyed on role, `latent`, and whether an
+ * a third party had vouched. None of that exists any
+ * more — an opportunity is born `negotiating` when a principal's agent opens
+ * it — so every branch collapsed to the same answer: the actors on a pairing
+ * may read it.
+ */
+export function canUserSeeOpportunity(actors, _status, userId) {
+    return actors.some((a) => a.userId === userId);
+}
+/**
+ * Whether an opportunity should appear on the viewer's radar (actionable =
+ * has a pending action for this user).
+ *
+ * Only `pending` is actionable, and only while the viewer has no `committed` event.
+ *
+ * The old rules 1-3 were about pre-kickoff states and vouching. Neither
+ * exists: a pairing is born `negotiating`, and a negotiating pairing is the
+ * agents' to work, not the principal's to action.
+ */
+export function isActionableForViewer(actors, status, viewerId, committedActorIds = []) {
+    if (status !== 'pending')
+        return false;
+    if (!actors.some((actor) => actor.userId === viewerId))
+        return false;
+    return !committedActorIds.includes(viewerId);
+}
+/** Soft targets for radar composition. */
+export const RADAR_SOFT_TARGETS = {
+    // 3 + 2 in a second category before that category was removed. The slots move to
+    // connections rather than shrinking the feed: the total a radar can hold is
+    // unchanged, and connections are the only kind of card left.
+    connection: 5,
+    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 - Unused; retained for call-site compatibility
+ * @returns Feed category
+ */
+export function classifyOpportunity(opp, _viewerId) {
+    if (opp.status === 'expired')
+        return 'expired';
+    return 'connection';
+}
+/**
+ * Select opportunities for the radar 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 function selectByComposition(opportunities, viewerId) {
+    const buckets = { connection: [], expired: [] };
+    for (const opp of opportunities) {
+        buckets[classifyOpportunity(opp, viewerId)].push(opp);
+    }
+    const targets = {
+        connection: RADAR_SOFT_TARGETS.connection,
+        expired: RADAR_SOFT_TARGETS.expired,
+    };
+    // First pass: fill each category up to its target.
+    const selected = {
+        connection: buckets.connection.slice(0, targets.connection),
+        expired: buckets.expired.slice(0, targets.expired),
+    };
+    // Second pass: redistribute unused slots, connection before expired.
+    let unusedSlots = (targets.connection + targets.expired)
+        - (selected.connection.length + selected.expired.length);
+    for (const category of ['connection', 'expired']) {
+        if (unusedSlots <= 0)
+            break;
+        const remaining = buckets[category].slice(selected[category].length);
+        const take = Math.min(remaining.length, unusedSlots);
+        selected[category].push(...remaining.slice(0, take));
+        unusedSlots -= take;
+    }
+    // Within each category, preserve original input order.
+    const indexMap = new Map(opportunities.map((opp, i) => [opp, i]));
+    const sortByOriginal = (a, b) => (indexMap.get(a) ?? 0) - (indexMap.get(b) ?? 0);
+    selected.connection.sort(sortByOriginal);
+    selected.expired.sort(sortByOriginal);
+    logger.info('Selected opportunities by composition', {
+        input: opportunities.length,
+        buckets: { connection: buckets.connection.length, expired: buckets.expired.length },
+        selected: { connection: selected.connection.length, expired: selected.expired.length },
+    });
+    return [...selected.connection, ...selected.expired];
+}
+/**
+ * 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.
+ * 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 function deduplicateByPerson(opportunities, viewerId) {
+    const bestByCounterpart = new Map();
+    const noCounterpart = [];
+    for (let i = 0; i < opportunities.length; i++) {
+        const opp = opportunities[i];
+        const counterpart = opp.actors.find((a) => a.userId !== viewerId);
+        if (!counterpart) {
+            noCounterpart.push({ opp, index: i });
+            continue;
+        }
+        const key = counterpart.userId;
+        const existing = bestByCounterpart.get(key);
+        if (!existing) {
+            bestByCounterpart.set(key, { opp, index: i });
+            continue;
+        }
+        const newConf = opp.interpretation?.confidence ?? -1;
+        const oldConf = existing.opp.interpretation?.confidence ?? -1;
+        if (newConf > oldConf) {
+            bestByCounterpart.set(key, { opp, index: i });
+        }
+    }
+    const all = [...bestByCounterpart.values(), ...noCounterpart];
+    all.sort((a, b) => a.index - b.index);
+    const result = all.map((entry) => entry.opp);
+    if (result.length < opportunities.length) {
+        dedupeByPersonLog.info('Deduped opportunities by person', {
+            input: opportunities.length,
+            output: result.length,
+        });
+    }
+    return result;
+}

package/dist/{opportunities → internal/opportunities}/radar/radar.graph.d.ts

@@ -2,7 +2,7 @@
  * Radar Graph: Build the opportunity radar view — a flat, presenter-texted
  * list of opportunity cards for a viewer, optionally scoped to one intent.
  *
- * Independent of ChatGraph. Flow:
+ * Flow:
  * loadOpportunities → checkPresenterCache → [generateCardText if misses]
  * → cachePresenterResults → normalizeItems
  *
@@ -10,11 +10,11 @@
  * OpportunityCache. Responses are a flat `items` array; clients bucket by
  * lifecycle status themselves.
  */
-import type { RadarGraphDatabase, OpportunityStatus } from '../../shared/interfaces/database.interface.js';
-import type { OpportunityCache } from '../../shared/interfaces/cache.interface.js';
+import type { RadarGraphDatabase, OpportunityStatus } from '../../../platform/database.js';
+import type { OpportunityCache } from '../../../platform/discovery/cache.js';
 import { RadarGraphState, type RadarCardItem, type RadarResponseItem } from './radar.state.js';
 import { OpportunityPresenter } from '../opportunity.presentation.js';
-import type { DebugMetaAgent } from '../../agents/agent.module.js';
+import type { DebugMetaAgent } from "../../../protocol/core.js";
 /** Database must satisfy both RadarGraphDatabase and presenter context (getProfile, getActiveIntents, getNetwork, getUser). */
 type RadarGraphDb = RadarGraphDatabase;
 export type RadarGraphInvokeInput = {
@@ -80,11 +80,11 @@ export declare class RadarGraphFactory {
         noCache: boolean;
         presentation: "full" | "skeleton";
         statuses: OpportunityStatus[] | undefined;
-        opportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+        opportunities: import("../../../platform/database.js").Opportunity[];
         cards: RadarCardItem[];
         items: RadarResponseItem[];
         cachedCards: Map<string, RadarCardItem>;
-        uncachedOpportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+        uncachedOpportunities: import("../../../platform/database.js").Opportunity[];
         error: string | undefined;
         meta: {
             totalOpportunities: number;
@@ -99,11 +99,11 @@ export declare class RadarGraphFactory {
         noCache?: boolean | import("@langchain/langgraph").OverwriteValue<boolean> | undefined;
         presentation?: "full" | "skeleton" | import("@langchain/langgraph").OverwriteValue<"full" | "skeleton"> | undefined;
         statuses?: OpportunityStatus[] | import("@langchain/langgraph").OverwriteValue<OpportunityStatus[] | undefined> | undefined;
-        opportunities?: import("../../shared/interfaces/database.entities.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../shared/interfaces/database.entities.js").Opportunity[]> | undefined;
+        opportunities?: import("../../../platform/database.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../../platform/database.js").Opportunity[]> | undefined;
         cards?: RadarCardItem[] | import("@langchain/langgraph").OverwriteValue<RadarCardItem[]> | undefined;
         items?: RadarResponseItem[] | import("@langchain/langgraph").OverwriteValue<RadarResponseItem[]> | undefined;
         cachedCards?: Map<string, RadarCardItem> | import("@langchain/langgraph").OverwriteValue<Map<string, RadarCardItem>> | undefined;
-        uncachedOpportunities?: import("../../shared/interfaces/database.entities.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../shared/interfaces/database.entities.js").Opportunity[]> | undefined;
+        uncachedOpportunities?: import("../../../platform/database.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../../platform/database.js").Opportunity[]> | undefined;
         error?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
         meta?: {
             totalOpportunities: number;
@@ -120,11 +120,11 @@ export declare class RadarGraphFactory {
         noCache: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
         presentation: import("@langchain/langgraph").BaseChannel<"full" | "skeleton", "full" | "skeleton" | import("@langchain/langgraph").OverwriteValue<"full" | "skeleton">, unknown>;
         statuses: import("@langchain/langgraph").BaseChannel<OpportunityStatus[] | undefined, OpportunityStatus[] | import("@langchain/langgraph").OverwriteValue<OpportunityStatus[] | undefined> | undefined, unknown>;
-        opportunities: import("@langchain/langgraph").BaseChannel<import("../../shared/interfaces/database.entities.js").Opportunity[], import("../../shared/interfaces/database.entities.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../shared/interfaces/database.entities.js").Opportunity[]>, unknown>;
+        opportunities: import("@langchain/langgraph").BaseChannel<import("../../../platform/database.js").Opportunity[], import("../../../platform/database.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../../platform/database.js").Opportunity[]>, unknown>;
         cards: import("@langchain/langgraph").BaseChannel<RadarCardItem[], RadarCardItem[] | import("@langchain/langgraph").OverwriteValue<RadarCardItem[]>, unknown>;
         items: import("@langchain/langgraph").BaseChannel<RadarResponseItem[], RadarResponseItem[] | import("@langchain/langgraph").OverwriteValue<RadarResponseItem[]>, unknown>;
         cachedCards: import("@langchain/langgraph").BaseChannel<Map<string, RadarCardItem>, Map<string, RadarCardItem> | import("@langchain/langgraph").OverwriteValue<Map<string, RadarCardItem>>, unknown>;
-        uncachedOpportunities: import("@langchain/langgraph").BaseChannel<import("../../shared/interfaces/database.entities.js").Opportunity[], import("../../shared/interfaces/database.entities.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../shared/interfaces/database.entities.js").Opportunity[]>, unknown>;
+        uncachedOpportunities: import("@langchain/langgraph").BaseChannel<import("../../../platform/database.js").Opportunity[], import("../../../platform/database.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../../platform/database.js").Opportunity[]>, unknown>;
         error: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
         meta: import("@langchain/langgraph").BaseChannel<{
             totalOpportunities: number;
@@ -143,11 +143,11 @@ export declare class RadarGraphFactory {
         noCache: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
         presentation: import("@langchain/langgraph").BaseChannel<"full" | "skeleton", "full" | "skeleton" | import("@langchain/langgraph").OverwriteValue<"full" | "skeleton">, unknown>;
         statuses: import("@langchain/langgraph").BaseChannel<OpportunityStatus[] | undefined, OpportunityStatus[] | import("@langchain/langgraph").OverwriteValue<OpportunityStatus[] | undefined> | undefined, unknown>;
-        opportunities: import("@langchain/langgraph").BaseChannel<import("../../shared/interfaces/database.entities.js").Opportunity[], import("../../shared/interfaces/database.entities.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../shared/interfaces/database.entities.js").Opportunity[]>, unknown>;
+        opportunities: import("@langchain/langgraph").BaseChannel<import("../../../platform/database.js").Opportunity[], import("../../../platform/database.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../../platform/database.js").Opportunity[]>, unknown>;
         cards: import("@langchain/langgraph").BaseChannel<RadarCardItem[], RadarCardItem[] | import("@langchain/langgraph").OverwriteValue<RadarCardItem[]>, unknown>;
         items: import("@langchain/langgraph").BaseChannel<RadarResponseItem[], RadarResponseItem[] | import("@langchain/langgraph").OverwriteValue<RadarResponseItem[]>, unknown>;
         cachedCards: import("@langchain/langgraph").BaseChannel<Map<string, RadarCardItem>, Map<string, RadarCardItem> | import("@langchain/langgraph").OverwriteValue<Map<string, RadarCardItem>>, unknown>;
-        uncachedOpportunities: import("@langchain/langgraph").BaseChannel<import("../../shared/interfaces/database.entities.js").Opportunity[], import("../../shared/interfaces/database.entities.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../shared/interfaces/database.entities.js").Opportunity[]>, unknown>;
+        uncachedOpportunities: import("@langchain/langgraph").BaseChannel<import("../../../platform/database.js").Opportunity[], import("../../../platform/database.js").Opportunity[] | import("@langchain/langgraph").OverwriteValue<import("../../../platform/database.js").Opportunity[]>, unknown>;
         error: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
         meta: import("@langchain/langgraph").BaseChannel<{
             totalOpportunities: number;
@@ -162,7 +162,7 @@ export declare class RadarGraphFactory {
             error: string;
             opportunities?: undefined;
         } | {
-            opportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+            opportunities: import("../../../platform/database.js").Opportunity[];
             error?: undefined;
         } | {
             error: string;
@@ -170,7 +170,7 @@ export declare class RadarGraphFactory {
         };
         checkPresenterCache: {
             cachedCards: Map<any, any>;
-            uncachedOpportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+            uncachedOpportunities: import("../../../platform/database.js").Opportunity[];
         };
         generateCardText: {
             cards: RadarCardItem[];
@@ -197,7 +197,7 @@ export declare function loadOpportunitiesNode(state: RadarState, deps: RadarGrap
     error: string;
     opportunities?: undefined;
 } | {
-    opportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+    opportunities: import("../../../platform/database.js").Opportunity[];
     error?: undefined;
 } | {
     error: string;
@@ -205,9 +205,9 @@ export declare function loadOpportunitiesNode(state: RadarState, deps: RadarGrap
 }>;
 export declare function checkPresenterCacheNode(state: RadarState, deps: RadarGraphDeps): Promise<{
     cachedCards: Map<any, any>;
-    uncachedOpportunities: import("../../shared/interfaces/database.entities.js").Opportunity[];
+    uncachedOpportunities: import("../../../platform/database.js").Opportunity[];
 }>;
-export declare function shouldGenerateCards(state: RadarState, deps: RadarGraphDeps): string;
+export declare function shouldGenerateCards(state: RadarState, _deps: RadarGraphDeps): string;
 export declare function generateCardTextNode(state: RadarState, deps: RadarGraphDeps): Promise<{
     cards: RadarCardItem[];
     agentTimings: DebugMetaAgent[];