@indexnetwork/protocol 6.12.1-rc.404.1 → 6.14.0-rc.406.1

package/dist/communities/application/indexer.state.js

@@ -0,0 +1,116 @@
+import { Annotation } from "@langchain/langgraph";
+/**
+ * Intent Index Graph State.
+ * Handles CRUD for the intent_indexes junction table (linking intents to networks).
+ *
+ * ## Signal assignment policy
+ *
+ * Two assignment paths, selected via `skipEvaluation`:
+ * - `true` (direct / manual_override): writes the link immediately with a fixed
+ *   score of 1 and mode `manual_override`.  No LLM call.
+ * - `false` (automatic / evaluated): loads intent + network context, calls
+ *   IntentIndexer from the signals public facade, then applies
+ *   `buildNetworkAssignmentDecision` to produce the threshold / metadata.
+ *   A no-prompt fast path skips the LLM when both prompts are absent.
+ *
+ * The IntentIndexer is injected as a constructor argument — communities never
+ * imports signals internals directly.
+ *
+ * Flow:
+ * START → router → {
+ *   create: assignNode (direct or evaluated) → END
+ *   read: readNode → END
+ *   delete: unassignNode → END
+ * }
+ *
+ * IND-546: canonical home — previously network/indexer/indexer.state.ts.
+ * LangGraph state carries IntentIndexerOutput and DebugMetaAgent which are
+ * cross-capability types; this file therefore belongs in the application layer.
+ */
+export const IntentNetworkGraphState = Annotation.Root({
+    // --- Core Inputs (from ChatGraph via ToolContext) ---
+    /** User performing the action. Always required. */
+    userId: (Annotation),
+    /** Target network for assign/read-by-network. From ChatGraph or tool arg. */
+    networkId: Annotation({
+        reducer: (_, next) => next,
+        default: () => undefined,
+    }),
+    /** Target intent for assign/read-by-intent. From tool arg. */
+    intentId: Annotation({
+        reducer: (_, next) => next,
+        default: () => undefined,
+    }),
+    /** Operation mode. */
+    operationMode: Annotation({
+        reducer: (curr, next) => next ?? curr,
+        default: () => 'read',
+    }),
+    // --- Create Mode Controls ---
+    /**
+     * When true, skip LLM evaluation and assign directly (manual_override).
+     * When false, run IntentIndexer evaluation (automatic mode).
+     */
+    skipEvaluation: Annotation({
+        reducer: (_, next) => next,
+        default: () => true,
+    }),
+    // --- Intermediate State (populated by nodes during graph execution) ---
+    /** Intent payload and metadata.  Null if intent not found. */
+    intent: Annotation({
+        reducer: (_, next) => next,
+        default: () => null,
+    }),
+    /** Network + member context.  Null if user not eligible. */
+    indexContext: Annotation({
+        reducer: (_, next) => next,
+        default: () => null,
+    }),
+    /** LLM evaluation result from IntentIndexer.  Null if evaluation was skipped. */
+    evaluation: Annotation({
+        reducer: (_, next) => next,
+        default: () => null,
+    }),
+    /** Final decision: should intent be in this network? */
+    shouldAssign: Annotation({
+        reducer: (_, next) => next,
+        default: () => undefined,
+    }),
+    /** Final score used for decision (0–1). */
+    finalScore: Annotation({
+        reducer: (_, next) => next,
+        default: () => undefined,
+    }),
+    /** Result of the assignment persistence operation. */
+    assignmentResult: Annotation({
+        reducer: (_, next) => next,
+        default: () => null,
+    }),
+    // --- Read Mode Controls ---
+    /** For read-by-network: pass userId when listing one user's intents in a network. */
+    queryUserId: Annotation({
+        reducer: (_, next) => next,
+        default: () => undefined,
+    }),
+    // --- Outputs ---
+    /** Output for read mode. */
+    readResult: Annotation({
+        reducer: (_, next) => next,
+        default: () => undefined,
+    }),
+    /** Output for create/delete modes. */
+    mutationResult: Annotation({
+        reducer: (_, next) => next,
+        default: () => undefined,
+    }),
+    /** Error message. */
+    error: Annotation({
+        reducer: (_, next) => next,
+        default: () => null,
+    }),
+    /** Timing records for each agent invocation within this graph run. */
+    agentTimings: Annotation({
+        reducer: (acc, val) => [...acc, ...val],
+        default: () => [],
+    }),
+});

package/dist/communities/application/membership.graph.d.ts

@@ -0,0 +1,270 @@
+import type { NetworkMembershipGraphDatabase } from "../ports/index.js";
+/**
+ * Factory class to build and compile the Network Membership Graph.
+ *
+ * Handles CRUD operations for the index_members table:
+ * - create: Add a member to a network (validates join policy and ownership)
+ * - read: List members of a network (validates caller is member)
+ * - delete: Remove a member from a network (owner-only)
+ *
+ * ## Membership authority policy
+ *
+ * Self-join (`targetUserId === userId`):
+ *   - Allowed only when `joinPolicy: 'anyone'`.
+ *   - Idempotent: already-a-member returns success.
+ *
+ * Invite others (`targetUserId !== userId`):
+ *   - Caller must be a member of the network.
+ *   - For `invite_only` networks, caller must also be the owner.
+ *   - Idempotent: already-a-member returns success.
+ *
+ * Remove member:
+ *   - Caller must be the network owner.
+ *   - Cannot remove the owner (delete the network instead).
+ *   - Cannot remove yourself via this path (use leave-network flow).
+ *
+ * Flow:
+ * START → routerNode → {addMemberNode | listMembersNode | removeMemberNode} → END
+ *
+ * IND-546: canonical home — previously network/membership/membership.graph.ts.
+ */
+export declare class NetworkMembershipGraphFactory {
+    private database;
+    constructor(database: NetworkMembershipGraphDatabase);
+    createGraph(): import("@langchain/langgraph").CompiledStateGraph<{
+        userId: string;
+        networkId: string;
+        operationMode: "delete" | "create" | "read";
+        targetUserId: string | undefined;
+        readResult: {
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | undefined;
+        mutationResult: {
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | undefined;
+        error: string | null;
+    }, {
+        userId?: string | undefined;
+        networkId?: string | undefined;
+        operationMode?: "delete" | "create" | "read" | import("@langchain/langgraph").OverwriteValue<"delete" | "create" | "read"> | undefined;
+        targetUserId?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
+        readResult?: {
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | import("@langchain/langgraph").OverwriteValue<{
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | undefined> | undefined;
+        mutationResult?: {
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | import("@langchain/langgraph").OverwriteValue<{
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | undefined> | undefined;
+        error?: string | import("@langchain/langgraph").OverwriteValue<string | null> | null | undefined;
+    }, "__start__" | "add_member" | "list_members" | "remove_member", {
+        userId: {
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+            (): import("@langchain/langgraph").LastValue<string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        networkId: {
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+            (): import("@langchain/langgraph").LastValue<string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        operationMode: import("@langchain/langgraph").BaseChannel<"delete" | "create" | "read", "delete" | "create" | "read" | import("@langchain/langgraph").OverwriteValue<"delete" | "create" | "read">, unknown>;
+        targetUserId: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        readResult: import("@langchain/langgraph").BaseChannel<{
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | undefined, {
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | import("@langchain/langgraph").OverwriteValue<{
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | undefined> | undefined, unknown>;
+        mutationResult: import("@langchain/langgraph").BaseChannel<{
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | undefined, {
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | import("@langchain/langgraph").OverwriteValue<{
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | undefined> | undefined, unknown>;
+        error: import("@langchain/langgraph").BaseChannel<string | null, string | import("@langchain/langgraph").OverwriteValue<string | null> | null, unknown>;
+    }, {
+        userId: {
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+            (): import("@langchain/langgraph").LastValue<string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        networkId: {
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+            (): import("@langchain/langgraph").LastValue<string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        operationMode: import("@langchain/langgraph").BaseChannel<"delete" | "create" | "read", "delete" | "create" | "read" | import("@langchain/langgraph").OverwriteValue<"delete" | "create" | "read">, unknown>;
+        targetUserId: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        readResult: import("@langchain/langgraph").BaseChannel<{
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | undefined, {
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | import("@langchain/langgraph").OverwriteValue<{
+            networkId: string;
+            count: number;
+            members: Array<{
+                userId: string;
+                name: string;
+                avatar: string | null;
+                permissions: string[];
+                intentCount: number;
+                joinedAt: Date;
+            }>;
+        } | undefined> | undefined, unknown>;
+        mutationResult: import("@langchain/langgraph").BaseChannel<{
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | undefined, {
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | import("@langchain/langgraph").OverwriteValue<{
+            success: boolean;
+            message?: string;
+            error?: string;
+        } | undefined> | undefined, unknown>;
+        error: import("@langchain/langgraph").BaseChannel<string | null, string | import("@langchain/langgraph").OverwriteValue<string | null> | null, unknown>;
+    }, import("@langchain/langgraph").StateDefinition, {
+        add_member: {
+            mutationResult: {
+                success: boolean;
+                error: string;
+                message?: undefined;
+            };
+        } | {
+            mutationResult: {
+                success: boolean;
+                message: string;
+                error?: undefined;
+            };
+        };
+        list_members: {
+            readResult: {
+                networkId: string;
+                count: number;
+                members: never[];
+            };
+            error: string;
+        } | {
+            readResult: {
+                networkId: string;
+                count: number;
+                members: {
+                    userId: string;
+                    name: string;
+                    avatar: string | null;
+                    permissions: string[];
+                    intentCount: number;
+                    joinedAt: Date;
+                }[];
+            };
+            error?: undefined;
+        } | {
+            error: string;
+            readResult?: undefined;
+        };
+        remove_member: {
+            mutationResult: {
+                success: boolean;
+                error: string;
+                message?: undefined;
+            };
+        } | {
+            mutationResult: {
+                success: boolean;
+                message: string;
+                error?: undefined;
+            };
+        };
+    }, unknown, unknown, []>;
+}

package/dist/communities/application/membership.graph.js

@@ -0,0 +1,229 @@
+import { StateGraph, START, END } from "@langchain/langgraph";
+import { protocolLogger } from "../../shared/observability/protocol.logger.js";
+import { timed } from "../../shared/observability/performance.js";
+import { NetworkMembershipGraphState } from "../domain/index.js";
+const logger = protocolLogger("NetworkMembershipGraphFactory");
+/**
+ * Factory class to build and compile the Network Membership Graph.
+ *
+ * Handles CRUD operations for the index_members table:
+ * - create: Add a member to a network (validates join policy and ownership)
+ * - read: List members of a network (validates caller is member)
+ * - delete: Remove a member from a network (owner-only)
+ *
+ * ## Membership authority policy
+ *
+ * Self-join (`targetUserId === userId`):
+ *   - Allowed only when `joinPolicy: 'anyone'`.
+ *   - Idempotent: already-a-member returns success.
+ *
+ * Invite others (`targetUserId !== userId`):
+ *   - Caller must be a member of the network.
+ *   - For `invite_only` networks, caller must also be the owner.
+ *   - Idempotent: already-a-member returns success.
+ *
+ * Remove member:
+ *   - Caller must be the network owner.
+ *   - Cannot remove the owner (delete the network instead).
+ *   - Cannot remove yourself via this path (use leave-network flow).
+ *
+ * Flow:
+ * START → routerNode → {addMemberNode | listMembersNode | removeMemberNode} → END
+ *
+ * IND-546: canonical home — previously network/membership/membership.graph.ts.
+ */
+export class NetworkMembershipGraphFactory {
+    constructor(database) {
+        this.database = database;
+    }
+    createGraph() {
+        // --- NODE DEFINITIONS ---
+        /**
+         * Add Member Node: Add a user as a member of a network.
+         *
+         * Two sub-paths:
+         * 1. Self-join (targetUserId === userId): only allowed for 'anyone' join policy.
+         * 2. Invite others (targetUserId !== userId): caller must be a member; owner-only
+         *    for invite_only networks.
+         */
+        const addMemberNode = async (state) => {
+            return timed("NetworkMembershipGraph.addMember", async () => {
+                logger.verbose("Add member to network", {
+                    userId: state.userId,
+                    networkId: state.networkId,
+                    targetUserId: state.targetUserId,
+                });
+                if (!state.targetUserId) {
+                    return { mutationResult: { success: false, error: "targetUserId is required." } };
+                }
+                try {
+                    const networkRecord = await this.database.getNetworkWithPermissions(state.networkId);
+                    if (!networkRecord) {
+                        return { mutationResult: { success: false, error: "Network not found." } };
+                    }
+                    const joinPolicy = networkRecord.permissions.joinPolicy;
+                    const isSelfJoin = state.targetUserId === state.userId;
+                    if (isSelfJoin) {
+                        // Self-join: only allowed for open networks
+                        if (joinPolicy !== 'anyone') {
+                            return {
+                                mutationResult: {
+                                    success: false,
+                                    error: "This network is invite-only. You cannot join without an invitation from an existing member.",
+                                },
+                            };
+                        }
+                        const result = await this.database.addMemberToNetwork(state.networkId, state.targetUserId, 'member');
+                        if (result.alreadyMember) {
+                            return { mutationResult: { success: true, message: "You are already a member of this network." } };
+                        }
+                        return { mutationResult: { success: true, message: `You have joined "${networkRecord.title}".` } };
+                    }
+                    // Inviting others: caller must be a member first
+                    const isMember = await this.database.isNetworkMember(state.networkId, state.userId);
+                    if (!isMember) {
+                        return { mutationResult: { success: false, error: "You must be a member of that network to add others." } };
+                    }
+                    if (joinPolicy === 'invite_only') {
+                        const isOwner = await this.database.isIndexOwner(state.networkId, state.userId);
+                        if (!isOwner) {
+                            return { mutationResult: { success: false, error: "Only the network owner can add members when the network is invite-only." } };
+                        }
+                    }
+                    const result = await this.database.addMemberToNetwork(state.networkId, state.targetUserId, 'member');
+                    if (result.alreadyMember) {
+                        return { mutationResult: { success: true, message: "That user is already a member of this network." } };
+                    }
+                    return { mutationResult: { success: true, message: "Member added to the network." } };
+                }
+                catch (err) {
+                    logger.error("Add member failed", { error: err });
+                    return {
+                        mutationResult: {
+                            success: false,
+                            error: err instanceof Error ? err.message : "Failed to add member.",
+                        },
+                    };
+                }
+            });
+        };
+        /**
+         * List Members Node: List all members of a network.
+         * Validates that the caller is a member before returning results.
+         */
+        const listMembersNode = async (state) => {
+            return timed("NetworkMembershipGraph.listMembers", async () => {
+                logger.verbose("List network members", {
+                    userId: state.userId,
+                    networkId: state.networkId,
+                });
+                try {
+                    const isMember = await this.database.isNetworkMember(state.networkId, state.userId);
+                    if (!isMember) {
+                        return {
+                            readResult: {
+                                networkId: state.networkId,
+                                count: 0,
+                                members: [],
+                            },
+                            error: "Network not found or you are not a member.",
+                        };
+                    }
+                    const members = await this.database.getNetworkMembersForMember(state.networkId, state.userId);
+                    return {
+                        readResult: {
+                            networkId: state.networkId,
+                            count: members.length,
+                            members: members.map((m) => ({
+                                userId: m.userId,
+                                name: m.name,
+                                avatar: m.avatar,
+                                permissions: m.permissions,
+                                intentCount: m.intentCount,
+                                joinedAt: m.joinedAt,
+                            })),
+                        },
+                    };
+                }
+                catch (err) {
+                    logger.error("List members failed", { error: err });
+                    if (err instanceof Error && err.message === "Access denied: Not a member of this network") {
+                        return { error: "You must be a member of that network." };
+                    }
+                    return { error: "Failed to fetch network members." };
+                }
+            });
+        };
+        /**
+         * Remove Member Node: Remove a member from a network (owner only).
+         *
+         * The owner themselves cannot be removed via this path.  To transfer or
+         * remove the owner, delete the network or promote another member first.
+         */
+        const removeMemberNode = async (state) => {
+            return timed("NetworkMembershipGraph.removeMember", async () => {
+                logger.verbose("Remove member from network", {
+                    userId: state.userId,
+                    networkId: state.networkId,
+                    targetUserId: state.targetUserId,
+                });
+                if (!state.targetUserId) {
+                    return { mutationResult: { success: false, error: "targetUserId is required." } };
+                }
+                // Cannot remove yourself via this flow
+                if (state.targetUserId === state.userId) {
+                    return { mutationResult: { success: false, error: "You cannot remove yourself. Use 'leave network' instead." } };
+                }
+                try {
+                    const isOwner = await this.database.isIndexOwner(state.networkId, state.userId);
+                    if (!isOwner) {
+                        return { mutationResult: { success: false, error: "Only the network owner can remove members." } };
+                    }
+                    const result = await this.database.removeMemberFromIndex(state.networkId, state.targetUserId);
+                    if (result.wasOwner) {
+                        return { mutationResult: { success: false, error: "Cannot remove the network owner." } };
+                    }
+                    if (result.notMember) {
+                        return { mutationResult: { success: false, error: "User is not a member of this network." } };
+                    }
+                    if (!result.success) {
+                        return { mutationResult: { success: false, error: "Failed to remove member." } };
+                    }
+                    return {
+                        mutationResult: {
+                            success: true,
+                            message: "Member removed from the network.",
+                        },
+                    };
+                }
+                catch (err) {
+                    logger.error("Remove member failed", { error: err });
+                    return { mutationResult: { success: false, error: "Failed to remove member." } };
+                }
+            });
+        };
+        // --- CONDITIONAL ROUTING ---
+        const routeByMode = (state) => {
+            switch (state.operationMode) {
+                case 'create': return 'add_member';
+                case 'read': return 'list_members';
+                case 'delete': return 'remove_member';
+                default: return 'list_members';
+            }
+        };
+        // --- GRAPH ASSEMBLY ---
+        const workflow = new StateGraph(NetworkMembershipGraphState)
+            .addNode("add_member", addMemberNode)
+            .addNode("list_members", listMembersNode)
+            .addNode("remove_member", removeMemberNode)
+            .addConditionalEdges(START, routeByMode, {
+            add_member: "add_member",
+            list_members: "list_members",
+            remove_member: "remove_member",
+        })
+            .addEdge("add_member", END)
+            .addEdge("list_members", END)
+            .addEdge("remove_member", END);
+        return workflow.compile();
+    }
+}