@indexnetwork/protocol 65.0.0 → 66.0.0-rc.609.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 66.0.0
+
+### Breaking changes
+
+- Opportunity copy comes only from the LLM presenter. `OpportunityPresenter.present()` and `presentCard()` throw on LLM failure, timeout, or invalid output instead of returning fallback copy; `isFallback` and `fallbackReason` are gone from their results.
+- Remove `presentOpportunity`, `stripUuids`, `truncateAtBoundary`, `safeFallbackSummary`, `DEFAULT_FALLBACK_HEADLINE`, `hasUnsupportedOpportunityClaim`, `stripUnsupportedOpportunityClaims`, and `stripUnsupportedOpportunityClaimsText` from the public entry point. The regex claim-safety guard is deleted; the presenter prompts carry the rule.
+- `readOpportunities` items no longer carry `reasoning`.
+- Remove `RadarGraphFactory` and the radar graph. Use `listOpportunityCards(deps, { viewerId, statuses, networkId?, intentId?, limit, noCache?, skeleton? })` for a presented card list and `presentOpportunityCard(deps, opportunity, viewerId, { intentId?, skeleton? })` for one card; both return `OpportunityCard`. `statuses` is required, and the list is newest first with one card per counterpart. A card whose presenter call fails is dropped from the list; `presentOpportunityCard` throws.
+- Rename `RadarGraphDatabase` to `OpportunityCardsDatabase` and `buildRadarCardPresentationCacheKey` to `buildOpportunityCardCacheKey` (keys now start with `card:`). Remove `RADAR_SOFT_TARGETS` and `selectByComposition`.
+
 ## 65.0.0
 
 ### Breaking changes

package/IMPLEMENTATION.md

@@ -128,26 +128,25 @@ negotiation state and presentation contracts.
 Optional capabilities default to a
 degraded-but-functional mode when omitted.
 
-## Graphs
+## Opportunity cards
 
-A `*GraphFactory` class is exported for each workflow:
+Presented opportunity cards are plain async functions over
+`{ database: OpportunityCardsDatabase, cache: OpportunityCache, presenter: OpportunityPresenter }`:
 
 ```typescript
 import {
-  RadarGraphFactory,
+  listOpportunityCards,
+  presentOpportunityCard,
 } from "@indexnetwork/protocol";
 ```
 
-Each factory takes its typed dependencies in the constructor and exposes a
-`.createGraph()` method that returns a compiled LangGraph ready for `.invoke()`.
+`listOpportunityCards` returns the viewer's opportunities in the requested
+statuses, newest first with one card per counterpart, serving cached cards and
+dropping any whose presenter call fails. `presentOpportunityCard` presents one
+opportunity and throws when the presenter fails.
 
-The intent and community graphs are the exceptions: they are reached through the
-`Intents` and `Networks` module classes rather than factories of their own (see
-[Intents](#intents) and [Networks](#networks) below).
-
-| Factory | Workflow |
-|---|---|
-| `RadarGraphFactory` | Build the radar view: flat presenter-card list, optionally intent-scoped |
+The intent and community graphs are reached through the `Intents` and `Networks`
+module classes (see [Intents](#intents) and [Networks](#networks) below).
 
 ## On-demand discovery
 

package/STABILITY.md

@@ -46,7 +46,6 @@ Covered by SemVer below. Breaking changes require a **major** bump.
 | **Public API** | Model config helpers, request scope helpers (`deriveAllowedNetworkIds`, `deriveDiscoveryNetworkIds`), `requestContext`. |
 | **Interfaces** | Every port you implement to inject infrastructure (databases, embedder, cache, scraper, integration, …). |
 | **Shared schemas** | Zod schemas + inferred types that cross the boundary (underspecification, identity, network-assignment, chat-context, …). |
-| **Graph factories** | `*GraphFactory` classes (for example, `RadarGraphFactory`). |
 | **Intents** | `Intents` — the whole signal capability as one class (lifecycle graph, verification, preparation) plus `IntentsDeps` and the `Prepare*` / `RecoveryField*` types. Replaced the six separate intent exports in 18.0.0. |
 | **Agents** | Structured LLM agents (`OpportunityEvaluator`, …). |
 

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { requestContext, setRequestContextStore } from "./internal/shared/observ
 export { setLoggerFactory } from "./internal/shared/observability/log.js";
 export { setTimingWrapper } from "./internal/shared/observability/performance.js";
 export type { Cache, CacheOptions, OpportunityCache } from "./platform/discovery/cache.js";
-export type { CompositeDatabase, UserDatabase, SystemDatabase, OpportunityDatabase, OpportunityControllerDatabase, RadarGraphDatabase, IntentGraphDatabase, Opportunity, OpportunityActor, OpportunityStatus, AssignmentNetworkMembership, IntentNetworkFinalAssignmentResult, CreateOpportunityData, IntentLifecycleStatus, TransitionLifecycleResult, NegotiationContextDatabase, NegotiationContextRecord, NegotiationContextOutcome, NegotiationContextTurn, } from "./platform/database.js";
+export type { CompositeDatabase, UserDatabase, SystemDatabase, OpportunityDatabase, OpportunityControllerDatabase, OpportunityCardsDatabase, IntentGraphDatabase, Opportunity, OpportunityActor, OpportunityStatus, AssignmentNetworkMembership, IntentNetworkFinalAssignmentResult, CreateOpportunityData, IntentLifecycleStatus, TransitionLifecycleResult, NegotiationContextDatabase, NegotiationContextRecord, NegotiationContextOutcome, NegotiationContextTurn, } from "./platform/database.js";
 export type { Embedder, VectorStoreOption, VectorSearchResult } from "./platform/discovery/embedder.js";
 export type { IntentFollowUp } from "./platform/runtime/follow-up.js";
 export type { Scraper } from "./platform/discovery/scraper.js";
@@ -43,14 +43,12 @@ export type { OpportunityEvidence } from "./protocol/schemas/network-assignment.
 export type { CreateIntentCounterpartyData, OpenedNegotiation, } from "./internal/opportunities/opportunity.counterparties.js";
 export { gatherPresenterContext, OpportunityPresenter, } from "./internal/opportunities/opportunity.presentation.js";
 export type { PresenterDatabase, } from "./internal/opportunities/opportunity.presentation.js";
-export { hasUnsupportedOpportunityClaim, stripUnsupportedOpportunityClaims, stripUnsupportedOpportunityClaims as stripUnsupportedOpportunityClaimsText, } from "./internal/shared/utils/claim-safety.js";
 export { getPrimaryActionLabel, } from "./internal/opportunities/opportunity.labels.js";
-export { buildApiChatCardPresentationCacheKey, buildRadarCardPresentationCacheKey, } from "./internal/opportunities/opportunity.presentation.js";
-export { presentOpportunity, stripUuids, truncateAtBoundary, } from "./internal/opportunities/opportunity.presentation.js";
+export { buildApiChatCardPresentationCacheKey, buildOpportunityCardCacheKey, } from "./internal/opportunities/opportunity.presentation.js";
 export type { UserInfo, } from "./internal/opportunities/opportunity.presentation.js";
-export { DEFAULT_FALLBACK_HEADLINE, safeFallbackSummary, } from "./internal/opportunities/opportunity.presentation.js";
-export { canUserSeeOpportunity, classifyOpportunity, isActionableForViewer, RADAR_SOFT_TARGETS, selectByComposition, validateOpportunityActors, } from "./internal/opportunities/opportunity.utils.js";
-export { RadarGraphFactory, } from "./internal/opportunities/radar/radar.graph.js";
+export { canUserSeeOpportunity, classifyOpportunity, isActionableForViewer, validateOpportunityActors, } from "./internal/opportunities/opportunity.utils.js";
+export { listOpportunityCards, presentOpportunityCard, } from "./internal/opportunities/opportunity.cards.js";
+export type { OpportunityCard, } from "./internal/opportunities/opportunity.cards.js";
 export { readOpportunities } from './internal/opportunities/opportunity.graph.modes.js';
 export { admitOpportunityEvent, projectOpportunity } from './internal/opportunities/opportunity.events.js';
 export type { OpportunityAdmission, OpportunityEventType, OpportunityLogEvent, OpportunityProjection, OpportunityProjectionStatus } from './internal/opportunities/opportunity.events.js';

package/dist/index.js

@@ -47,13 +47,10 @@ export { normalizeTelegramHandle } from './internal/shared/utils/telegram-handle
  */
 export { pairKeyOf, } from "./internal/opportunities/opportunity.counterparties.js";
 export { gatherPresenterContext, OpportunityPresenter, } from "./internal/opportunities/opportunity.presentation.js";
-export { hasUnsupportedOpportunityClaim, stripUnsupportedOpportunityClaims, stripUnsupportedOpportunityClaims as stripUnsupportedOpportunityClaimsText, } from "./internal/shared/utils/claim-safety.js";
 export { getPrimaryActionLabel, } from "./internal/opportunities/opportunity.labels.js";
-export { buildApiChatCardPresentationCacheKey, buildRadarCardPresentationCacheKey, } from "./internal/opportunities/opportunity.presentation.js";
-export { presentOpportunity, stripUuids, truncateAtBoundary, } from "./internal/opportunities/opportunity.presentation.js";
-export { DEFAULT_FALLBACK_HEADLINE, safeFallbackSummary, } from "./internal/opportunities/opportunity.presentation.js";
-export { canUserSeeOpportunity, classifyOpportunity, isActionableForViewer, RADAR_SOFT_TARGETS, selectByComposition, validateOpportunityActors, } from "./internal/opportunities/opportunity.utils.js";
-export { RadarGraphFactory, } from "./internal/opportunities/radar/radar.graph.js";
+export { buildApiChatCardPresentationCacheKey, buildOpportunityCardCacheKey, } from "./internal/opportunities/opportunity.presentation.js";
+export { canUserSeeOpportunity, classifyOpportunity, isActionableForViewer, validateOpportunityActors, } from "./internal/opportunities/opportunity.utils.js";
+export { listOpportunityCards, presentOpportunityCard, } from "./internal/opportunities/opportunity.cards.js";
 export { readOpportunities } from './internal/opportunities/opportunity.graph.modes.js';
 export { admitOpportunityEvent, projectOpportunity } from './internal/opportunities/opportunity.events.js';
 export { resolveDiscoveryNetworkScope, renderDiscoveryNetworkContext } from './protocol/discovery.rules.js';

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

@@ -0,0 +1,78 @@
+/**
+ * Opportunity cards: presenter-texted cards for a viewer, as a list or one at
+ * a time. The list loads, filters, and dedupes the viewer's opportunities,
+ * serves cached cards, and presents the misses through OpportunityPresenter.
+ */
+import type { Opportunity, OpportunityCardsDatabase, OpportunityStatus } from '../../platform/database.js';
+import type { OpportunityCache } from '../../platform/discovery/cache.js';
+import { OpportunityPresenter } from './opportunity.presentation.js';
+/** One opportunity with its presenter-driven display contract. */
+export interface OpportunityCard {
+    opportunityId: string;
+    createdAt?: string;
+    /** Lifecycle status of the underlying opportunity at render time. */
+    status?: OpportunityStatus;
+    userId: string;
+    name: string;
+    avatar: string | null;
+    mainText: string;
+    cta: string;
+    headline?: string;
+    primaryActionLabel: string;
+    secondaryActionLabel: string;
+    mutualIntentsLabel: string;
+    narratorChip?: {
+        name: string;
+        text: string;
+        avatar?: string | null;
+        userId?: string;
+    };
+    /** Viewer's role in this opportunity (e.g. 'party', 'agent', 'patient', 'peer'). */
+    viewerRole?: string;
+    /**
+     * True for a skeleton card: identity fields are real but mainText/cta are
+     * empty because the presenter was skipped. Never cached.
+     */
+    presentationPending?: boolean;
+}
+/** Everything card presentation reaches for. */
+export interface OpportunityCardsDeps {
+    database: OpportunityCardsDatabase;
+    cache: OpportunityCache;
+    presenter: OpportunityPresenter;
+}
+/**
+ * Present one opportunity as a card for the viewer.
+ *
+ * @param deps - Database, cache, and presenter.
+ * @param opportunity - The opportunity to present.
+ * @param viewerId - The viewing user.
+ * @param options - `intentId` focuses viewer context on one intent; `skeleton` skips the presenter.
+ * @returns The card, or null when the counterpart's name cannot be resolved.
+ * @throws When the presenter fails.
+ */
+export declare function presentOpportunityCard(deps: OpportunityCardsDeps, opportunity: Opportunity, viewerId: string, options?: {
+    intentId?: string;
+    skeleton?: boolean;
+}): Promise<OpportunityCard | null>;
+/**
+ * List the viewer's opportunities in the given statuses as presented cards,
+ * newest first, one card per counterpart. Cards whose presentation fails are
+ * dropped.
+ *
+ * @param deps - Database, cache, and presenter.
+ * @param input - Viewer, statuses, optional network/intent scope, limit, cache bypass, skeleton mode.
+ * @returns The cards and the number of opportunities selected.
+ */
+export declare function listOpportunityCards(deps: OpportunityCardsDeps, input: {
+    viewerId: string;
+    statuses: OpportunityStatus[];
+    networkId?: string;
+    intentId?: string;
+    limit: number;
+    noCache?: boolean;
+    skeleton?: boolean;
+}): Promise<{
+    cards: OpportunityCard[];
+    totalOpportunities: number;
+}>;

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

@@ -0,0 +1,165 @@
+/**
+ * Opportunity cards: presenter-texted cards for a viewer, as a list or one at
+ * a time. The list loads, filters, and dedupes the viewer's opportunities,
+ * serves cached cards, and presents the misses through OpportunityPresenter.
+ */
+import { protocolLogger } from '../shared/observability/protocol.logger.js';
+import { buildOpportunityCardCacheKey, gatherPresenterContext } from './opportunity.presentation.js';
+import { loadNegotiationContext } from './negotiation-context.loader.js';
+import { canUserSeeOpportunity, isActionableForViewer } from './opportunity.utils.js';
+import { getPrimaryActionLabel, SECONDARY_ACTION_LABEL } from './opportunity.labels.js';
+const logger = protocolLogger('OpportunityCards');
+const PRESENTATION_CONCURRENCY = 50;
+const CARD_CACHE_TTL = 24 * 60 * 60;
+const ROLE_PRIORITY = new Map([
+    ['patient', 0],
+    ['party', 1],
+    ['agent', 2],
+    ['peer', 3],
+]);
+/** Prefer direct counterpart roles, then a stable sort by user id. */
+function pickDisplayCounterpartActor(opportunity, viewerId) {
+    const candidates = opportunity.actors.filter((actor) => actor.userId !== viewerId);
+    return [...candidates].sort((a, b) => {
+        const aPriority = ROLE_PRIORITY.get(a.role) ?? 99;
+        const bPriority = ROLE_PRIORITY.get(b.role) ?? 99;
+        if (aPriority !== bPriority)
+            return aPriority - bPriority;
+        return a.userId.localeCompare(b.userId);
+    })[0] ?? null;
+}
+function counterpartUserIds(opportunity, viewerId) {
+    return new Set(opportunity.actors.map((a) => a.userId).filter((id) => id && id !== viewerId));
+}
+/**
+ * Present one opportunity as a card for the viewer.
+ *
+ * @param deps - Database, cache, and presenter.
+ * @param opportunity - The opportunity to present.
+ * @param viewerId - The viewing user.
+ * @param options - `intentId` focuses viewer context on one intent; `skeleton` skips the presenter.
+ * @returns The card, or null when the counterpart's name cannot be resolved.
+ * @throws When the presenter fails.
+ */
+export async function presentOpportunityCard(deps, opportunity, viewerId, options = {}) {
+    const { database } = deps;
+    const viewerRole = opportunity.actors.find((a) => a.userId === viewerId)?.role ?? 'party';
+    const counterpart = pickDisplayCounterpartActor(opportunity, viewerId);
+    if (!counterpart)
+        return null;
+    const user = await database.getUser(counterpart.userId).catch(() => null);
+    let name = user?.name?.trim();
+    if (!name) {
+        const profile = await database.getProfile(counterpart.userId).catch(() => null);
+        name = profile?.identity?.name?.trim();
+    }
+    if (!name)
+        return null;
+    const identity = {
+        opportunityId: opportunity.id,
+        createdAt: opportunity.createdAt.toISOString(),
+        status: opportunity.status,
+        userId: counterpart.userId,
+        name,
+        avatar: user?.avatar ?? null,
+        primaryActionLabel: getPrimaryActionLabel(viewerRole),
+        secondaryActionLabel: SECONDARY_ACTION_LABEL,
+        viewerRole,
+    };
+    if (options.skeleton) {
+        return { ...identity, mainText: '', cta: '', mutualIntentsLabel: 'Shared interests', presentationPending: true };
+    }
+    const [context, negotiationContext] = await Promise.all([
+        gatherPresenterContext(database, opportunity, viewerId, counterpart.userId, options.intentId),
+        loadNegotiationContext(database, opportunity.id, opportunity.status, viewerId),
+    ]);
+    const presentation = await deps.presenter.presentCard({
+        ...context,
+        opportunityStatus: opportunity.status,
+        ...(negotiationContext ? { negotiationContext } : {}),
+    });
+    return {
+        ...identity,
+        mainText: presentation.personalizedSummary,
+        cta: presentation.suggestedAction,
+        headline: presentation.headline,
+        mutualIntentsLabel: presentation.mutualIntentsLabel,
+        narratorChip: { name: 'Index', text: presentation.narratorRemark },
+    };
+}
+/**
+ * List the viewer's opportunities in the given statuses as presented cards,
+ * newest first, one card per counterpart. Cards whose presentation fails are
+ * dropped.
+ *
+ * @param deps - Database, cache, and presenter.
+ * @param input - Viewer, statuses, optional network/intent scope, limit, cache bypass, skeleton mode.
+ * @returns The cards and the number of opportunities selected.
+ */
+export async function listOpportunityCards(deps, input) {
+    const { viewerId, intentId } = input;
+    const raw = await deps.database.getOpportunitiesForUser(viewerId, {
+        limit: Math.min(150, Math.max(50, input.limit * 3)),
+        statuses: input.statuses,
+        ...(input.networkId ? { networkId: input.networkId } : {}),
+        ...(intentId ? { scopeType: 'intent', scopeId: intentId } : {}),
+    });
+    const requested = new Set(input.statuses);
+    const visible = raw
+        .filter((opp) => requested.has(opp.status) && canUserSeeOpportunity(opp.actors, opp.status, viewerId))
+        .filter((opp) => opp.status !== 'pending'
+        || isActionableForViewer(opp.actors, opp.status, viewerId, opp.committedActorIds ?? []))
+        .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+    const seen = new Set();
+    const opportunities = visible.filter((opp) => {
+        const ids = counterpartUserIds(opp, viewerId);
+        if ([...ids].some((id) => seen.has(id)))
+            return false;
+        for (const id of ids)
+            seen.add(id);
+        return true;
+    }).slice(0, input.limit);
+    const cacheable = (opp) => opp.status !== 'negotiating';
+    const keyFor = (opp) => buildOpportunityCardCacheKey(opp.id, opp.status, viewerId, intentId);
+    const cacheableOpps = input.noCache ? [] : opportunities.filter(cacheable);
+    const cached = new Map();
+    if (cacheableOpps.length > 0) {
+        try {
+            const hits = await deps.cache.mget(cacheableOpps.map(keyFor));
+            cacheableOpps.forEach((opp, i) => {
+                const hit = hits[i];
+                if (hit)
+                    cached.set(opp.id, { ...hit, status: opp.status });
+            });
+        }
+        catch (error) {
+            logger.warn('card cache read failed, presenting all', { error });
+        }
+    }
+    const cards = [];
+    for (let i = 0; i < opportunities.length; i += PRESENTATION_CONCURRENCY) {
+        const chunk = opportunities.slice(i, i + PRESENTATION_CONCURRENCY);
+        cards.push(...await Promise.all(chunk.map(async (opp) => {
+            const hit = cached.get(opp.id);
+            if (hit)
+                return hit;
+            try {
+                const card = await presentOpportunityCard(deps, opp, viewerId, { intentId, skeleton: input.skeleton });
+                if (card && !card.presentationPending && cacheable(opp)) {
+                    await deps.cache.set(keyFor(opp), card, { ttl: CARD_CACHE_TTL }).catch((error) => {
+                        logger.warn('card cache write failed', { opportunityId: opp.id, error });
+                    });
+                }
+                return card;
+            }
+            catch (error) {
+                logger.warn('presenter failed, dropping card', { opportunityId: opp.id, error });
+                return null;
+            }
+        })));
+    }
+    return {
+        cards: cards.filter((card) => card !== null),
+        totalOpportunities: opportunities.length,
+    };
+}

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

@@ -29,7 +29,6 @@ export declare function readOpportunities(deps: {
             networkName: string;
             connectedWith: string[];
             suggestedBy: null;
-            reasoning: string;
             status: import("../../platform/database.js").OpportunityStatus;
             category: string;
             confidence: number | null;

package/dist/internal/opportunities/opportunity.graph.modes.js

@@ -10,7 +10,6 @@
  * `readResult` / `mutationResult` exactly as before.
  */
 import { timed } from '../shared/observability/performance.js';
-import { safeFallbackSummary } from "./opportunity.presentation.js";
 import { protocolLogger } from '../shared/observability/protocol.logger.js';
 const readLog = protocolLogger('Opportunity:Read');
 /**
@@ -101,10 +100,6 @@ export async function readOpportunities(deps, request) {
                     networkName: networkRecord?.title ?? (actorNetworkId ?? ''),
                     connectedWith,
                     suggestedBy,
-                    reasoning: safeFallbackSummary(opp.interpretation?.reasoning, {
-                        counterpartName: connectedWith.join(' and '),
-                        emptyText: 'Connection opportunity',
-                    }),
                     status: opp.status,
                     category,
                     confidence: confidence != null ? confidence : null,

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

@@ -1,5 +1,3 @@
-/** Max chars for main text in minimal opportunity cards. Full text shown so cards are not truncated. */
-export declare const MINIMAL_MAIN_TEXT_MAX_CHARS = 2000;
 /** Hardcoded button labels for opportunity cards (not LLM-generated). */
 export declare const PRIMARY_ACTION_LABEL_DEFAULT = "Start Chat";
 export declare const SECONDARY_ACTION_LABEL = "Skip";

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

@@ -1,5 +1,3 @@
-/** Max chars for main text in minimal opportunity cards. Full text shown so cards are not truncated. */
-export const MINIMAL_MAIN_TEXT_MAX_CHARS = 2000;
 /** Hardcoded button labels for opportunity cards (not LLM-generated). */
 export const PRIMARY_ACTION_LABEL_DEFAULT = "Start Chat";
 export const SECONDARY_ACTION_LABEL = "Skip";