@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0

package/dist/internal/opportunities/negotiation-context.loader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Negotiation context loader: given an opportunity, fetches the turn log of
+ * the negotiation attached to it so the card presenter can explain *why* the
+ * opportunity surfaced.
+ *
+ * An expired opportunity's negotiation no longer matters, so the loader
+ * returns null for it without asking the host.
+ */
+import type { NegotiationContextDatabase, NegotiationContextOutcome, NegotiationContextTurn, OpportunityStatus } from '../../platform/database.js';
+/** Snapshot of a negotiation surfaced to the presenter. */
+export interface NegotiationContext {
+    status: OpportunityStatus;
+    turnCount: number;
+    turns: NegotiationContextTurn[];
+    outcome?: NegotiationContextOutcome;
+}
+/**
+ * Loads the negotiation context for an opportunity.
+ *
+ * @param db - The host's negotiation read.
+ * @param opportunityId - The opportunity being presented.
+ * @param opportunityStatus - Its current status.
+ * @param viewerId - Who the card is being presented to.
+ * @returns The context, or null when no meaningful negotiation exists.
+ */
+export declare function loadNegotiationContext(db: NegotiationContextDatabase, opportunityId: string, opportunityStatus: OpportunityStatus, viewerId: string): Promise<NegotiationContext | null>;

package/dist/internal/opportunities/negotiation-context.loader.js

@@ -0,0 +1,36 @@
+/**
+ * Negotiation context loader: given an opportunity, fetches the turn log of
+ * the negotiation attached to it so the card presenter can explain *why* the
+ * opportunity surfaced.
+ *
+ * An expired opportunity's negotiation no longer matters, so the loader
+ * returns null for it without asking the host.
+ */
+import { protocolLogger } from '../shared/observability/protocol.logger.js';
+const logger = protocolLogger('NegotiationContextLoader');
+const STATUSES_WITH_NO_NEGOTIATION = ['expired'];
+/**
+ * Loads the negotiation context for an opportunity.
+ *
+ * @param db - The host's negotiation read.
+ * @param opportunityId - The opportunity being presented.
+ * @param opportunityStatus - Its current status.
+ * @param viewerId - Who the card is being presented to.
+ * @returns The context, or null when no meaningful negotiation exists.
+ */
+export async function loadNegotiationContext(db, opportunityId, opportunityStatus, viewerId) {
+    if (STATUSES_WITH_NO_NEGOTIATION.includes(opportunityStatus)) {
+        return null;
+    }
+    const record = await db.readNegotiationContext(opportunityId, viewerId);
+    if (!record) {
+        logger.verbose('No negotiation found for opportunity', { opportunityId, opportunityStatus });
+        return null;
+    }
+    return {
+        status: opportunityStatus,
+        turnCount: record.turns.length,
+        turns: record.turns,
+        ...(record.outcome ? { outcome: record.outcome } : {}),
+    };
+}

package/dist/{opportunities → internal/opportunities}/opportunity.actor.d.ts

@@ -1,4 +1,4 @@
-import type { CreateOpportunityData, OpportunityActor } from '../shared/interfaces/database.interface.js';
+import type { CreateOpportunityData, OpportunityActor } from '../../platform/database.js';
 /**
  * Normalize an actor intent value while preserving protocol string IDs.
  * Null-like model sentinels are represented by absence in persisted actors.

package/dist/{opportunities → internal/opportunities}/opportunity.actor.js

@@ -8,7 +8,13 @@ export function normalizeOpportunityActorIntent(value) {
     const normalized = value.trim();
     if (normalized.length === 0
         || normalized.toLowerCase() === 'null'
-        || normalized.toLowerCase() === 'undefined') {
+        || normalized.toLowerCase() === 'undefined'
+        // Python's null literal, which evaluators do emit: a candidate actor was
+        // persisted with `intent: "None"` in dev and every downstream reader took
+        // it for a real binding — the counterparty seat was granted a
+        // consultation (whose park writes `recipientIntentId` straight at the
+        // intents table) on a signal that does not exist.
+        || normalized.toLowerCase() === 'none') {
         return undefined;
     }
     return normalized;

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

@@ -0,0 +1,17 @@
+/**
+ * The counterparty side of a pair discovery scored.
+ *
+ * Discovery does not stage the pair anywhere: it hands the host the pair and
+ * the host opens the opportunity and its negotiation. {@link pairKeyOf} is what
+ * keeps that idempotent across both principals' runs.
+ */
+/**
+ * Stable identity of a two-intent pair within a network, independent of which
+ * side's discovery run found it.
+ *
+ * Ids are length-prefixed rather than joined on a separator: an id containing
+ * the separator would otherwise let two different pairs produce one key, and
+ * this key is a uniqueness constraint.
+ */
+export declare function pairKeyOf(networkId: string, intentA: string, intentB: string): string;
+export type { CreateIntentCounterpartyData, OpenedNegotiation, } from '../../platform/database.js';

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

@@ -0,0 +1,19 @@
+/**
+ * The counterparty side of a pair discovery scored.
+ *
+ * Discovery does not stage the pair anywhere: it hands the host the pair and
+ * the host opens the opportunity and its negotiation. {@link pairKeyOf} is what
+ * keeps that idempotent across both principals' runs.
+ */
+/**
+ * Stable identity of a two-intent pair within a network, independent of which
+ * side's discovery run found it.
+ *
+ * Ids are length-prefixed rather than joined on a separator: an id containing
+ * the separator would otherwise let two different pairs produce one key, and
+ * this key is a uniqueness constraint.
+ */
+export function pairKeyOf(networkId, intentA, intentB) {
+    const [low, high] = intentA <= intentB ? [intentA, intentB] : [intentB, intentA];
+    return [networkId, low, high].map((part) => `${part.length}:${part}`).join('');
+}

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

@@ -0,0 +1,38 @@
+/** Append-only opportunity facts. The row status is a projection of these. */
+export type OpportunityEventType = 'opened' | 'agreed' | 'committed' | 'declined' | 'expired';
+export interface OpportunityLogEvent {
+    type: OpportunityEventType;
+    /** Set only for `committed`. */
+    actorUserId: string | null;
+}
+export type OpportunityProjectionStatus = 'negotiating' | 'pending' | 'accepted' | 'rejected' | 'expired';
+export interface OpportunityProjection {
+    status: OpportunityProjectionStatus;
+    committedActorIds: string[];
+}
+export type OpportunityAdmission = {
+    ok: true;
+    projection: OpportunityProjection;
+    introduction: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Fold an opportunity's event log into the status readers filter on.
+ *
+ * @param events - Log order, oldest first. The first event is `opened`.
+ * @param actorIds - Distinct named humans on the opportunity.
+ * @returns The projected status. A log that breaks the admission rules throws.
+ */
+export declare function projectOpportunity(events: OpportunityLogEvent[], actorIds: string[]): OpportunityProjection;
+/**
+ * Decide whether one event may be appended, and what the row becomes.
+ *
+ * @param events - Events already stored, oldest first.
+ * @param actorIds - Distinct named humans on the opportunity.
+ * @param event - The event to append.
+ * @returns The next projection, or why the event is illegal. `introduction` is
+ *   true only when this commit is the one that completes the set.
+ */
+export declare function admitOpportunityEvent(events: OpportunityLogEvent[], actorIds: string[], event: OpportunityLogEvent): OpportunityAdmission;

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

@@ -0,0 +1,94 @@
+const TERMINAL = new Set(['accepted', 'rejected', 'expired']);
+const EMPTY = { status: 'negotiating', committedActorIds: [], opened: false };
+function visible(state) {
+    return { status: state.status, committedActorIds: state.committedActorIds };
+}
+/**
+ * Fold an opportunity's event log into the status readers filter on.
+ *
+ * @param events - Log order, oldest first. The first event is `opened`.
+ * @param actorIds - Distinct named humans on the opportunity.
+ * @returns The projected status. A log that breaks the admission rules throws.
+ */
+export function projectOpportunity(events, actorIds) {
+    return visible(events.reduce((projection, event) => {
+        const next = applyEvent(projection, actorIds, event);
+        if (!next.ok)
+            throw new Error(next.error);
+        return next.state;
+    }, EMPTY));
+}
+/**
+ * Decide whether one event may be appended, and what the row becomes.
+ *
+ * @param events - Events already stored, oldest first.
+ * @param actorIds - Distinct named humans on the opportunity.
+ * @param event - The event to append.
+ * @returns The next projection, or why the event is illegal. `introduction` is
+ *   true only when this commit is the one that completes the set.
+ */
+export function admitOpportunityEvent(events, actorIds, event) {
+    let state = EMPTY;
+    for (const existing of events) {
+        const step = applyEvent(state, actorIds, existing);
+        if (!step.ok)
+            return step;
+        state = step.state;
+    }
+    const admitted = applyEvent(state, actorIds, event);
+    if (!admitted.ok)
+        return admitted;
+    return { ok: true, introduction: admitted.introduction, projection: visible(admitted.state) };
+}
+function applyEvent(projection, actorIds, event) {
+    if (event.type === 'opened') {
+        if (projection.opened)
+            return { ok: false, error: 'This opportunity is already open.' };
+        return { ok: true, introduction: false, state: { ...EMPTY, opened: true } };
+    }
+    if (!projection.opened)
+        return { ok: false, error: 'This opportunity is not open.' };
+    if (TERMINAL.has(projection.status)) {
+        return { ok: false, error: 'This opportunity can no longer change.' };
+    }
+    if (event.type === 'agreed') {
+        if (projection.status !== 'negotiating')
+            return { ok: false, error: 'Agents have not agreed yet.' };
+        return { ok: true, introduction: false, state: { ...projection, status: 'pending' } };
+    }
+    if (event.type === 'declined' || event.type === 'expired') {
+        if (projection.status !== 'negotiating' && projection.status !== 'pending') {
+            return { ok: false, error: 'This opportunity can no longer change.' };
+        }
+        return {
+            ok: true,
+            introduction: false,
+            state: {
+                opened: true,
+                status: event.type === 'declined' ? 'rejected' : 'expired',
+                committedActorIds: projection.committedActorIds,
+            },
+        };
+    }
+    if (projection.status !== 'pending')
+        return { ok: false, error: 'Agents have not agreed yet.' };
+    const actorUserId = event.actorUserId;
+    if (!actorUserId || !actorIds.includes(actorUserId)) {
+        return { ok: false, error: 'You are not part of this opportunity.' };
+    }
+    if (projection.committedActorIds.includes(actorUserId)) {
+        return { ok: false, error: 'You have already acted on this opportunity.' };
+    }
+    const committedActorIds = [...projection.committedActorIds, actorUserId];
+    const distinct = [...new Set(actorIds)];
+    const complete = distinct.length > 0 && distinct.every((id) => committedActorIds.includes(id));
+    return {
+        ok: true,
+        introduction: complete,
+        state: {
+            opened: true,
+            status: complete ? 'accepted' : 'pending',
+            committedActorIds,
+        },
+    };
+}

package/dist/{opportunities → internal/opportunities}/opportunity.feed-selection.d.ts

@@ -1,16 +1,12 @@
-import type { DeliveryLedger } from '../shared/interfaces/delivery-ledger.interface.js';
-import type { ChatGraphCompositeDatabase, Opportunity } from '../shared/interfaces/database.interface.js';
+import type { CompositeDatabase, Opportunity } from '../../platform/database.js';
 export interface OpportunityFeedSelectionInput {
-    reader: Pick<ChatGraphCompositeDatabase, 'getOpportunitiesForUser'>;
-    deliveryLedger?: Pick<DeliveryLedger, 'getDeliveredOpportunities'>;
+    reader: Pick<CompositeDatabase, 'getOpportunitiesForUser'>;
     viewerId: string;
     networkId?: string;
     intentScope: {
         scopeType?: 'intent';
         scopeId?: string;
     };
-    isMcp: boolean;
-    includeDigestMarkers?: boolean;
     displayLimit: number;
     warn: (message: string, data: Record<string, unknown>) => void;
 }
@@ -18,13 +14,11 @@ export interface OpportunityFeedSelection {
     opportunities: Opportunity[];
     dedupedCount: number;
     skippedIds: string[];
-    redeliveryIds: Set<string>;
     fetchedCount: number;
-    isDigestMode: boolean;
 }
 /**
  * Selects actionable opportunities for the chat/feed surface. The caller actor
  * check is deliberately the first post-read filter so non-actor rows cannot
- * affect digest suppression, selection, or downstream profile/presentation reads.
+ * affect selection or downstream profile/presentation reads.
  */
 export declare function selectOpportunityFeed(args: OpportunityFeedSelectionInput): Promise<OpportunityFeedSelection>;

package/dist/internal/opportunities/opportunity.feed-selection.js

@@ -0,0 +1,40 @@
+import { deduplicateByPerson, selectByComposition } from './opportunity.utils.js';
+const ACTIONABLE_FEED_STATUSES = ['pending'];
+const FEED_FETCH_LIMIT = 30;
+/**
+ * Selects actionable opportunities for the chat/feed surface. The caller actor
+ * check is deliberately the first post-read filter so non-actor rows cannot
+ * affect selection or downstream profile/presentation reads.
+ */
+export async function selectOpportunityFeed(args) {
+    const fetched = await args.reader.getOpportunitiesForUser(args.viewerId, {
+        networkId: args.networkId,
+        ...args.intentScope,
+        statuses: ACTIONABLE_FEED_STATUSES,
+        limit: FEED_FETCH_LIMIT,
+    });
+    const skippedIds = [];
+    const callerScoped = fetched.filter((opportunity) => {
+        if (opportunity.actors.some((actor) => actor.userId === args.viewerId))
+            return true;
+        args.warn('Opportunity feed: skipping opportunity where caller is not an actor', {
+            opportunityId: opportunity.id,
+            viewerId: args.viewerId,
+            actorUserIds: opportunity.actors
+                .map((actor) => actor.userId)
+                .filter((userId) => typeof userId === 'string'),
+        });
+        skippedIds.push(opportunity.id);
+        return false;
+    });
+    const deduped = deduplicateByPerson(callerScoped, args.viewerId);
+    const selected = deduped.length > 0
+        ? selectByComposition(deduped, args.viewerId)
+        : deduped;
+    return {
+        opportunities: selected.slice(0, args.displayLimit),
+        dedupedCount: deduped.length,
+        skippedIds,
+        fetchedCount: fetched.length,
+    };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The opportunity operations that are not discovery.
+ *
+ * These used to be graph nodes reached through an `operationMode` conditional
+ * edge at START — nine one-node paths sharing a state machine they never used.
+ * They are plain async functions now; callers invoke the one they mean. Only
+ * the discovery pipeline still needs a graph.
+ *
+ * Each returns the same shape the corresponding node returned, so callers read
+ * `readResult` / `mutationResult` exactly as before.
+ */
+import type { Id } from '../../platform/database.js';
+import type { OpportunityDatabase } from '../../platform/database.js';
+/**
+ * Read mode: list opportunities for the user, optionally filtered by networkId.
+ * Fast path — no LLM calls.
+ */
+export declare function readOpportunities(deps: {
+    database: OpportunityDatabase;
+}, request: {
+    userId: Id<'users'>;
+    networkId?: Id<'networks'>;
+}): Promise<{
+    readResult: {
+        count: number;
+        message: string;
+        opportunities: {
+            id: string;
+            networkName: string;
+            connectedWith: string[];
+            suggestedBy: null;
+            reasoning: string;
+            status: import("../../platform/database.js").OpportunityStatus;
+            category: string;
+            confidence: number | null;
+            source: string | null;
+        }[];
+    };
+}>;

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

@@ -0,0 +1,138 @@
+/**
+ * The opportunity operations that are not discovery.
+ *
+ * These used to be graph nodes reached through an `operationMode` conditional
+ * edge at START — nine one-node paths sharing a state machine they never used.
+ * They are plain async functions now; callers invoke the one they mean. Only
+ * the discovery pipeline still needs a graph.
+ *
+ * Each returns the same shape the corresponding node returned, so callers read
+ * `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');
+/**
+ * Read mode: list opportunities for the user, optionally filtered by networkId.
+ * Fast path — no LLM calls.
+ */
+export async function readOpportunities(deps, request) {
+    return timed("OpportunityGraph.read", async () => {
+        readLog.verbose('Listing opportunities', {
+            userId: request.userId,
+            networkId: request.networkId,
+        });
+        try {
+            let networkIdFilter;
+            if (request.networkId) {
+                const [isMember, isOwner] = await Promise.all([
+                    deps.database.isNetworkMember(request.networkId, request.userId),
+                    deps.database.isNetworkOwner(request.networkId, request.userId),
+                ]);
+                if (!isMember && !isOwner) {
+                    return {
+                        readResult: { count: 0, opportunities: [], message: 'Network not found or you are not a member.' },
+                    };
+                }
+                networkIdFilter = request.networkId;
+            }
+            const rawList = await deps.database.getOpportunitiesForUser(request.userId, {
+                limit: 30,
+                ...(networkIdFilter ? { networkId: networkIdFilter } : {}),
+            });
+            const list = rawList.filter((opp) => opp.status !== 'expired');
+            if (list.length === 0) {
+                return {
+                    readResult: {
+                        count: 0,
+                        message: 'You have no opportunities yet. Create or refine an approved signal; matching runs in the background. Review persisted results later from the opportunities read.',
+                        opportunities: [],
+                    },
+                };
+            }
+            // Dedupe by counterpart set (same people = one row) so chat does not show "You and X" per network
+            const counterpartKey = (opp) => opp.actors
+                .filter((a) => a.userId !== request.userId)
+                .map((a) => a.userId)
+                .sort()
+                .join(',');
+            const byKey = new Map();
+            for (const opp of list) {
+                const key = counterpartKey(opp);
+                const existing = byKey.get(key);
+                const conf = Number(opp.interpretation?.confidence ?? opp.confidence ?? 0);
+                const existingConf = existing ? Number(existing.interpretation?.confidence ?? existing.confidence ?? 0) : 0;
+                const oppTime = opp.updatedAt instanceof Date ? opp.updatedAt.getTime() : new Date(opp.updatedAt).getTime();
+                const existingTime = existing
+                    ? (existing.updatedAt instanceof Date ? existing.updatedAt.getTime() : new Date(existing.updatedAt).getTime())
+                    : 0;
+                if (!existing || conf > existingConf || (conf === existingConf && oppTime > existingTime)) {
+                    byKey.set(key, opp);
+                }
+            }
+            const dedupedList = [...byKey.values()];
+            const enriched = await Promise.all(dedupedList.map(async (opp) => {
+                // "Other parties" = every actor who is not the current user.
+                const otherParties = opp.actors.filter((a) => a.userId !== request.userId);
+                const partyIds = otherParties.map((a) => a.userId);
+                const idsToResolve = partyIds;
+                // Use the counterpart's (non-viewer) networkId — it reflects where the match was found.
+                // actors[0] is typically the viewer with an arbitrary first-target-network value.
+                const counterpartActor = opp.actors.find((a) => a.userId !== request.userId);
+                const actorNetworkId = counterpartActor?.networkId ?? opp.actors[0]?.networkId;
+                const [networkRecord, ...profileAndUserPairs] = await Promise.all([
+                    actorNetworkId ? deps.database.getNetwork(actorNetworkId) : Promise.resolve(null),
+                    ...idsToResolve.map(async (uid) => {
+                        const [profile, user] = await Promise.all([
+                            deps.database.getProfile(uid),
+                            deps.database.getUser(uid),
+                        ]);
+                        return (profile?.identity?.name ?? user?.name ?? 'Unknown');
+                    }),
+                ]);
+                const connectedWith = profileAndUserPairs.slice(0, partyIds.length);
+                const suggestedBy = null;
+                const category = opp.interpretation?.category ?? 'connection';
+                const confidence = opp.interpretation?.confidence ?? (opp.confidence ? Number(opp.confidence) : null);
+                const source = opp.detection?.source ? (OPPORTUNITY_SOURCE_LABEL[opp.detection.source] ?? opp.detection.source) : null;
+                return {
+                    id: opp.id,
+                    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,
+                    source,
+                };
+            }));
+            return {
+                readResult: {
+                    count: enriched.length,
+                    message: `You have ${enriched.length} opportunity(ies).`,
+                    opportunities: enriched,
+                },
+            };
+        }
+        catch (err) {
+            readLog.error('Failed', { error: err });
+            return {
+                readResult: { count: 0, opportunities: [], message: 'Failed to list opportunities.' },
+            };
+        }
+    });
+}
+/** Human-readable label per detection source, for the read-mode listing. */
+const OPPORTUNITY_SOURCE_LABEL = {
+    chat: 'Suggested in chat',
+    opportunity_graph: 'System match',
+    manual: 'Manual',
+    cron: 'Scheduled',
+    member_added: 'Member added',
+    // Read-only history: nothing stamps this source any more, but old rows carry it.
+};

package/dist/{opportunities → internal/opportunities}/opportunity.labels.d.ts

@@ -1,8 +1,7 @@
-/** Max chars for main text in minimal opportunity cards (chat tool payload). Full text shown so cards are not truncated. */
+/** 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_INTRODUCER = "Good match";
 export declare const PRIMARY_ACTION_LABEL_DEFAULT = "Start Chat";
 export declare const SECONDARY_ACTION_LABEL = "Skip";
 /** Returns the primary action label based on the viewer's role. */
-export declare function getPrimaryActionLabel(viewerRole: string): string;
+export declare function getPrimaryActionLabel(_viewerRole: string): string;

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

@@ -0,0 +1,9 @@
+/** 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";
+/** Returns the primary action label based on the viewer's role. */
+export function getPrimaryActionLabel(_viewerRole) {
+    return PRIMARY_ACTION_LABEL_DEFAULT;
+}