@indexnetwork/protocol 14.3.2-rc.477.1 → 16.1.1-rc.478.1

package/dist/shared/interfaces/database.interface.js

@@ -1 +1,9 @@
+/**
+ * The database port, re-exported as one surface.
+ *
+ * The declarations moved into sibling modules — entities, the four query
+ * groups that compose `Database`, the access-scoped views, negotiation
+ * persistence, and the capability-narrowed aliases. Importers keep using this
+ * path; nothing about the types changed.
+ */
 export {};

package/dist/shared/interfaces/database.member-queries.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Database operations for contacts, premises, and user contexts.
+ */
+import type { NetworkAssignmentMetadata } from '../schemas/network-assignment.schema.js';
+import type { PremiseAnalysis, PremiseAssertion, PremiseProvenance, PremiseRecord, PremiseValidity } from './database.entities.js';
+/** Contact, premise and user-context operations. */
+export interface DatabaseMemberQueries {
+    /** Create a ghost user (unregistered contact) with empty profile. */
+    createGhostUser(data: {
+        name: string;
+        email: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Upsert a contact membership in the owner's personal network (index_members with permissions=['contact']). */
+    upsertContactMembership(ownerId: string, contactUserId: string, options?: {
+        restore?: boolean;
+    }): Promise<void>;
+    /**
+     * Finds an existing DM conversation between two users, or creates one.
+     * Uses a unique `dmPair` column (sorted user IDs joined by ':') to
+     * prevent duplicate DMs under concurrency. Used by the Start Chat flow
+     * (Plan B Task 8) to atomically surface the h2h conversation when
+     * accepting an opportunity.
+     */
+    getOrCreateDM(userA: string, userB: string, participantType?: 'user' | 'agent'): Promise<{
+        id: string;
+    }>;
+    /**
+     * Clears hiddenAt for a user on a conversation, making it visible in their
+     * conversation list again. Called by startChat when reusing an existing DM
+     * that the user had previously hidden.
+     */
+    unhideConversation(userId: string, conversationId: string): Promise<void>;
+    /** Hard-delete a contact membership from the owner's personal network. */
+    hardDeleteContactMembership(ownerId: string, contactUserId: string): Promise<void>;
+    /** Get all contact members from the owner's personal network with user details. */
+    getContactMembers(ownerId: string): Promise<Array<{
+        userId: string;
+        user: {
+            id: string;
+            name: string;
+            email: string;
+            avatar: string | null;
+            isGhost: boolean;
+        };
+    }>>;
+    /** Clear a reverse opt-out (reactivate soft-deleted contact membership in another user's personal network). */
+    clearReverseOptOut(ownerId: string, otherUserId: string): Promise<void>;
+    /**
+     * Returns the IDs of personal networks where the given user is a contact member.
+     * Used for auto-assigning new intents to personal networks of contacts who imported this user.
+     *
+     * @param userId - The user whose contact memberships to look up
+     * @returns Array of personal network IDs
+     */
+    getPersonalIndexesForContact(userId: string): Promise<{
+        networkId: string;
+    }[]>;
+    /** Find a user by email. */
+    getUserByEmail(email: string): Promise<{
+        id: string;
+        name: string;
+        email: string;
+        isGhost: boolean;
+    } | null>;
+    createPremise(input: {
+        userId: string;
+        assertion: PremiseAssertion;
+        provenance: PremiseProvenance;
+        analysis?: PremiseAnalysis;
+        validity: PremiseValidity;
+        embedding?: number[];
+    }): Promise<PremiseRecord>;
+    getPremise(premiseId: string): Promise<PremiseRecord | null>;
+    getPremisesForUser(userId: string, status?: 'ACTIVE' | 'RETRACTED' | 'EXPIRED'): Promise<PremiseRecord[]>;
+    /**
+     * Retrieve a user's premises assigned to one of the provided networks.
+     * Optional for older/test adapters; OpportunityGraph falls back to capped
+     * getPremisesForUser results when unavailable.
+     */
+    getPremisesForUserInNetworks?(userId: string, networkIds: string[], status?: 'ACTIVE' | 'RETRACTED' | 'EXPIRED', limit?: number): Promise<PremiseRecord[]>;
+    updatePremise(premiseId: string, updates: {
+        assertion?: PremiseAssertion;
+        analysis?: PremiseAnalysis;
+        validity?: PremiseValidity;
+        embedding?: number[];
+        status?: 'ACTIVE' | 'RETRACTED' | 'EXPIRED';
+        retractedAt?: Date;
+    }): Promise<PremiseRecord>;
+    assignPremiseToNetwork(premiseId: string, networkId: string, relevancyScore: number, assignmentMetadata?: NetworkAssignmentMetadata): Promise<void>;
+    getPremiseNetworks(premiseId: string): Promise<Array<{
+        networkId: string;
+        relevancyScore: number | null;
+        assignmentMetadata?: NetworkAssignmentMetadata | null;
+    }>>;
+    /**
+     * Cosine similarity search against premise embeddings, scoped to shared networks.
+     * Used by the opportunity graph's premise discovery path (path D).
+     */
+    searchPremisesBySimilarity(params: {
+        embedding: number[];
+        networkIds: string[];
+        excludeUserId: string;
+        limit: number;
+        minScore?: number;
+    }): Promise<Array<{
+        premiseId: string;
+        userId: string;
+        networkId: string;
+        assertionText: string;
+        similarity: number;
+    }>>;
+    /**
+     * Cosine similarity search against user_context embeddings, scoped to shared networks.
+     * Matches only per-network context rows (the global networkId-null row is never a
+     * candidate), excluding the discovering user. Optional — lightweight-mode
+     * context-to-context discovery no-ops when the adapter omits it.
+     */
+    searchUserContextsBySimilarity?(params: {
+        embedding: number[];
+        networkIds: string[];
+        excludeUserId: string;
+        limit: number;
+        minScore?: number;
+    }): Promise<Array<{
+        contextId: string;
+        userId: string;
+        networkId: string;
+        text: string;
+        similarity: number;
+    }>>;
+    /**
+     * Batched version of premise similarity search. Executes one bounded DB call
+     * for all selected source premises instead of one query per source premise.
+     * Optional for older/test adapters; OpportunityGraph falls back to the
+     * single-source method when unavailable.
+     */
+    searchPremisesBySimilarityBatch?(params: {
+        sources: Array<{
+            premiseId: string;
+            embedding: number[];
+        }>;
+        networkIds: string[];
+        excludeUserId: string;
+        limitPerSource: number;
+        minScore?: number;
+    }): Promise<Array<{
+        sourcePremiseId: string;
+        premiseId: string;
+        userId: string;
+        networkId: string;
+        assertionText: string;
+        similarity: number;
+    }>>;
+    /**
+     * Find the single most-similar ACTIVE premise belonging to the SAME user whose
+     * cosine similarity to `embedding` meets or exceeds `threshold`. Used by the
+     * premise graph to skip near-duplicate premises on create. Returns null when no
+     * active premise clears the threshold (or the user has none with an embedding).
+     * Optional so older/test adapters can omit it — the premise graph skips dedup
+     * when it is unavailable.
+     */
+    findSimilarActivePremise?(params: {
+        userId: string;
+        embedding: number[];
+        threshold: number;
+    }): Promise<{
+        premiseId: string;
+        assertionText: string;
+        similarity: number;
+    } | null>;
+    /**
+     * Upsert a user context. Pass a concrete `networkId` for a per-network row, or
+     * `null` for the user's single global (profile-replacing) context row.
+     * Creates or updates the synthesized context paragraph + embedding.
+     */
+    upsertUserContext(params: {
+        userId: string;
+        networkId: string | null;
+        text: string;
+        embedding: number[];
+        premiseHash: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /**
+     * Get the user context for a specific user+network pair, or the global row when
+     * `networkId` is `null`.
+     */
+    getUserContext(userId: string, networkId: string | null): Promise<{
+        id: string;
+        text: string;
+        embedding: number[];
+        premiseHash: string;
+        generatedAt: Date;
+    } | null>;
+    /**
+     * Get user contexts for a user across all their networks. Includes the global
+     * row (`networkId: null`) when present.
+     */
+    getUserContexts(userId: string): Promise<Array<{
+        id: string;
+        networkId: string | null;
+        text: string;
+        embedding: number[];
+        premiseHash: string;
+        generatedAt: Date;
+    }>>;
+    /**
+     * Cosine similarity search against intent embeddings using a context embedding.
+     * Restores the profile→intent cross-search deleted when Path B was removed.
+     */
+    searchIntentsByContextEmbedding(params: {
+        embedding: number[];
+        networkIds: string[];
+        excludeUserId: string;
+        limit: number;
+        minScore?: number;
+    }): Promise<Array<{
+        intentId: string;
+        userId: string;
+        networkId: string;
+        payload: string;
+        summary: string | null;
+        similarity: number;
+    }>>;
+}

package/dist/shared/interfaces/database.member-queries.js

@@ -0,0 +1,4 @@
+/**
+ * Database operations for contacts, premises, and user contexts.
+ */
+export {};

package/dist/shared/interfaces/database.negotiation.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Negotiation-specific persistence: continuation receipts, private
+ * consultations, and the queries the negotiation graph depends on.
+ */
+import type { NegotiationOpportunityLifecycle, OpportunityStatus } from './database.entities.js';
+import type { Database } from './database.port.js';
+/**
+ * Negotiation-specific query operations not covered by generic
+ * conversation/task primitives.
+ */
+/** A user's ordinary follow-up answer stored on established shared opportunity metadata. */
+export interface NegotiationUserAnswer {
+    questionId: string;
+    selectedOptions: string[];
+    freeText?: string;
+    answeredAt: string;
+}
+export interface NegotiationPrivateConsultation {
+    recipientUserId: string;
+    recipientIntentId: string;
+    kind: 'answer' | 'dismiss' | 'timeout';
+    selectedOptions: string[];
+    freeText?: string;
+}
+export interface NegotiationContinuationExecution {
+    taskId: string;
+    settlementId: string;
+    opportunityId: string;
+    userId: string;
+    recipientIntentId: string;
+    networkId: string;
+    intentFingerprint: string;
+    opportunityStatus: string;
+    opportunityUpdatedAt: string;
+    counterpartyUserId: string;
+    counterpartyIntentId: string;
+    successorTaskId: string;
+    conversationId: string;
+    token: string;
+    fence: number;
+    leaseExpiresAt: string;
+    consultation: NegotiationPrivateConsultation;
+}
+export interface NegotiationContinuationReceipt {
+    priorTaskId: string;
+    settlementId: string;
+    successorTaskId: string;
+    fence: number;
+    outcome: 'accepted' | 'rejected' | 'stalled' | 'waiting_for_agent' | 'input_required';
+}
+export interface NegotiationQueries {
+    /** Capture canonical material binding before arming an ask-user timeout. */
+    captureNegotiationAskUserBinding(input: {
+        taskId: string;
+        turnContext: Record<string, unknown>;
+        settlementId: string;
+        recipientUserId: string;
+        recipientIntentId: string;
+        opportunityId: string;
+        networkId: string;
+        continuationExecution?: NegotiationContinuationExecution;
+    }): Promise<{
+        version: 2;
+        settlementId: string;
+        recipientUserId: string;
+        recipientIntentId: string;
+        opportunityId: string;
+        networkId: string;
+        intentFingerprint: string;
+        opportunityStatus: string;
+        opportunityUpdatedAt: string;
+        counterpartyUserId: string;
+        counterpartyIntentId: string;
+    }>;
+    /**
+     * Persists the full negotiation turn context (source/candidate user contexts,
+     * seed assessment, index context, discovery query) onto the task metadata so
+     * that polling agents can reconstruct the same context the system agent sees
+     * in-process. Merges into `metadata.turnContext`, leaving other keys intact.
+     * @param taskId - Task whose metadata to enrich
+     * @param turnContext - Absolute (source/candidate) view of the negotiation context
+     */
+    setTaskTurnContext(taskId: string, turnContext: Record<string, unknown>, continuationExecution?: NegotiationContinuationExecution): Promise<void>;
+    /**
+     * Merges a screen-gate decision (P2.1 shadow mode) into
+     * `metadata.screenDecision`, leaving other metadata keys intact. Optional so
+     * existing fakes/wireups remain valid; when absent the screen node logs the
+     * decision and proceeds without persisting.
+     * @param taskId - Task whose metadata to enrich
+     * @param screenDecision - ScreenDecisionRecord (decision, evidence, mode, timing)
+     */
+    setTaskScreenDecision?(taskId: string, screenDecision: Record<string, unknown>, continuationExecution?: NegotiationContinuationExecution): Promise<void>;
+    /**
+     * Merges an applied deadlock→bargaining shift record (IND-428) into
+     * `metadata.deadlockShift`, leaving other metadata keys intact. Internal
+     * analytics only — API surfaces must never project this key. Optional so
+     * existing fakes/wireups remain valid; when absent the turn node logs the
+     * shift and proceeds without persisting.
+     * @param taskId - Task whose metadata to enrich
+     * @param deadlockShift - DeadlockShiftRecord (run length, threshold, turn, seat, timing)
+     */
+    setTaskDeadlockShift?(taskId: string, deadlockShift: Record<string, unknown>, continuationExecution?: NegotiationContinuationExecution): Promise<void>;
+    /**
+     * Returns the most-recently-created task whose metadata carries
+     * `type: 'negotiation'` and `opportunityId: <id>`. Returns null if no
+     * negotiation has been started for that opportunity yet.
+     */
+    getNegotiationTaskForOpportunity(opportunityId: string): Promise<{
+        id: string;
+        conversationId: string;
+        state: string;
+        metadata: Record<string, unknown> | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    /**
+     * Returns the most-recently-created task whose metadata carries
+     * `type: 'negotiation'` on the given conversation, regardless of
+     * opportunityId or direction. Used by the init node's conversation-scoped
+     * tie-break: symmetric concurrent starts carry different opportunityIds, so
+     * the opportunity-scoped lookup above cannot see the competing task.
+     * Optional so existing fakes/wireups remain valid; when absent the
+     * tie-break is skipped (pre-stamp behavior).
+     */
+    getLatestNegotiationTaskForConversation?(conversationId: string): Promise<{
+        id: string;
+        conversationId: string;
+        state: string;
+        metadata: Record<string, unknown> | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    /**
+     * Returns user answers collected by the questioner system for a given
+     * opportunity. Reads `metadata.userAnswers` from the opportunities table.
+     * Used by the negotiation graph to inject between-session context into
+     * continuation prompts.
+     */
+    getOpportunityUserAnswers(opportunityId: string): Promise<NegotiationUserAnswer[]>;
+}
+/**
+ * Database dependency for the negotiation graph (A2A conversation/task/artifact
+ * persistence). Composes generic conversation ops with negotiation-specific queries.
+ *
+ * Access layer: ConversationDatabaseAdapter
+ */
+export type NegotiationGraphDatabase = Pick<Database, 'getOrCreateDM' | 'getUserContext'> & NegotiationQueries & {
+    /**
+     * Update the status of an opportunity. Called from the negotiation graph to
+     * advance the opportunity lifecycle (negotiating -> pending/rejected/stalled).
+     * Returns only the narrow { id, status } needed by the graph, not the full Opportunity.
+     */
+    updateOpportunityStatus(id: string, status: OpportunityStatus, acceptedBy?: string, continuationExecution?: NegotiationContinuationExecution): Promise<{
+        id: string;
+        status: OpportunityStatus;
+    } | null>;
+    /** Persists a negotiation turn message within a conversation. */
+    createMessage(data: {
+        conversationId: string;
+        senderId: string;
+        role: 'user' | 'agent';
+        parts: unknown[];
+        taskId?: string;
+        metadata?: Record<string, unknown> | null;
+        continuationExecution?: NegotiationContinuationExecution;
+    }): Promise<{
+        id: string;
+        senderId: string;
+        role: 'user' | 'agent';
+        parts: unknown;
+        createdAt: Date;
+    }>;
+    /**
+     * Atomically claims an exact persisted opportunity attempt, promotes it to
+     * negotiating, and creates its task. Returns null when the status/version is
+     * stale or another qualifying task already owns the attempt.
+     */
+    createNegotiationTaskForAttempt(input: {
+        conversationId: string;
+        opportunityId: string;
+        expectedStatus: OpportunityStatus;
+        expectedUpdatedAt: Date;
+        metadata: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+        conversationId: string;
+        state: string;
+    } | null>;
+    /** Creates a generic task to track a non-attempt-bound lifecycle. */
+    createTask(conversationId: string, metadata?: Record<string, unknown>): Promise<{
+        id: string;
+        conversationId: string;
+        state: string;
+    }>;
+    /**
+     * Under a deterministic settlement lock, validate the exact canceled ask_user
+     * task and return its existing successor or create one. Never consults a
+     * latest-task lookup.
+     */
+    getOrCreateNegotiationContinuationTask(input: {
+        priorTaskId: string;
+        settlementId: string;
+        conversationId: string;
+        opportunityId: string;
+        metadata: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+        conversationId: string;
+        state: string;
+        created: boolean;
+    } | null>;
+    /** Transitions a task to a new state (e.g. working, completed, failed). */
+    updateTaskState(taskId: string, state: string, statusMessage?: unknown, continuationExecution?: NegotiationContinuationExecution, parkGeneration?: string): Promise<{
+        id: string;
+        conversationId: string;
+        state: string;
+    }>;
+    /** Persists a negotiation outcome artifact attached to a task. */
+    createArtifact(data: {
+        taskId: string;
+        name?: string;
+        parts: unknown[];
+        metadata?: Record<string, unknown> | null;
+        continuationExecution?: NegotiationContinuationExecution;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Lists negotiation tasks where the given user is source or candidate. */
+    getTasksForUser(userId: string, options?: {
+        state?: string;
+    }): Promise<Array<{
+        id: string;
+        conversationId: string;
+        state: string;
+        metadata: Record<string, unknown> | null;
+        createdAt: Date;
+        updatedAt: Date;
+    }>>;
+    /**
+     * Resolves each opportunity to the intent carried by the given user's actor.
+     * Missing opportunities or actor intents are returned as null so callers can
+     * enforce fail-closed scope filtering for legacy task metadata.
+     */
+    getIntentIdsForOpportunities(opportunityIds: string[], userId: string): Promise<Record<string, string | null>>;
+    /**
+     * Batch-loads current opportunity lifecycle evidence for negotiation
+     * narration. Implementations must omit opportunities that do not contain the
+     * authenticated owner actor. Optional for backward-compatible hosts; callers
+     * must treat a missing implementation as unavailable evidence, never as acceptance.
+     */
+    getOpportunityLifecyclesForNegotiations?(opportunityIds: string[], ownerUserId: string): Promise<Record<string, NegotiationOpportunityLifecycle>>;
+    /** Gets a specific task by ID. */
+    getTask(taskId: string): Promise<{
+        id: string;
+        conversationId: string;
+        state: string;
+        metadata: Record<string, unknown> | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    /**
+     * Gets all messages for a conversation, ordered by creation time.
+     *
+     * `taskId` is the originating negotiation task (IND-569). Optional so legacy
+     * hosts remain valid; when omitted, prior negotiation turns cannot be
+     * attributed to their opportunity and degrade to the unattributed
+     * prior-dialogue block rather than being mixed into the current opportunity.
+     */
+    getMessagesForConversation(conversationId: string): Promise<Array<{
+        id: string;
+        senderId: string;
+        role: 'user' | 'agent';
+        parts: unknown[];
+        createdAt: Date;
+        taskId?: string | null;
+    }>>;
+    /** Gets artifacts for a task (e.g. negotiation outcome). */
+    getArtifactsForTask(taskId: string): Promise<Array<{
+        id: string;
+        name: string | null;
+        parts: unknown[];
+        metadata: Record<string, unknown> | null;
+    }>>;
+};
+/**
+ * Database interface for opportunity controller (API).
+ *
+ * Access layer: Both UserDatabase + SystemDatabase (API handles auth)
+ */
+/**
+ * Optional atomic outbox for Lens B outcome capture (IND-434). Passed to a
+ * winning owner-action transition so the append-only outcome event is written
+ * in the SAME transaction as the status change:
+ *   - a rolled-back action leaves NO event;
+ *   - a committed eligible action produces EXACTLY one event;
+ *   - `result.inserted` is set to true by the adapter only when a NEW row was
+ *     written (idempotent retries / duplicates set it false), so the caller can
+ *     gate post-commit mining on a genuine first insert.
+ *
+ * `event` is typed `unknown` (the api-side outcome-event insert row, cast by the
+ * adapter) to keep the protocol layer free of database-schema imports. The
+ * actor-resolution mode is a transaction-time precondition: selected-intent
+ * captures require that exact actor intent, while unscoped captures require the
+ * recipient to still have one unambiguous actor-intent scope.
+ */

package/dist/shared/interfaces/database.negotiation.js

@@ -0,0 +1,26 @@
+/**
+ * Negotiation-specific persistence: continuation receipts, private
+ * consultations, and the queries the negotiation graph depends on.
+ */
+export {};
+/**
+ * Database interface for opportunity controller (API).
+ *
+ * Access layer: Both UserDatabase + SystemDatabase (API handles auth)
+ */
+/**
+ * Optional atomic outbox for Lens B outcome capture (IND-434). Passed to a
+ * winning owner-action transition so the append-only outcome event is written
+ * in the SAME transaction as the status change:
+ *   - a rolled-back action leaves NO event;
+ *   - a committed eligible action produces EXACTLY one event;
+ *   - `result.inserted` is set to true by the adapter only when a NEW row was
+ *     written (idempotent retries / duplicates set it false), so the caller can
+ *     gate post-commit mining on a genuine first insert.
+ *
+ * `event` is typed `unknown` (the api-side outcome-event insert row, cast by the
+ * adapter) to keep the protocol layer free of database-schema imports. The
+ * actor-resolution mode is a transaction-time precondition: selected-intent
+ * captures require that exact actor intent, while unscoped captures require the
+ * recipient to still have one unambiguous actor-intent scope.
+ */