@memberjunction/server 5.38.0 → 5.40.0

package/src/resolvers/IntegrationProgressResolver.ts

@@ -0,0 +1,220 @@
+/**
+ * IntegrationProgressResolver — GraphQL subscription surface for long-running
+ * integration events (plan.md §11).
+ *
+ * Exposes a SINGLE @Subscription topic carrying structured progress notifications
+ * for every kind of integration run — metadata refresh, connector creation, sync,
+ * and RSU — so a UI can stream live updates instead of polling
+ * IntegrationTailRunEvents. Filtering by `runID`, `companyIntegrationID`, and `kind`
+ * happens in the subscription filter, exactly like PipelineProgressResolver.
+ *
+ * Wiring through the MJ event system: server-side producers (the
+ * IntegrationProgressEmitter, the connector-creation pipeline, the sync engine,
+ * the RSU pipeline) call the exported {@link PublishIntegrationProgress} helper,
+ * which forwards onto the same `PubSubManager` PubSub infrastructure that backs
+ * PipelineProgress and cache-invalidation events — NOT a parallel mechanism.
+ */
+import { Resolver, Subscription, Root, ObjectType, Field, Int, Arg } from 'type-graphql';
+import { LogError } from '@memberjunction/core';
+import type {
+    IntegrationRunKind,
+    IntegrationProgressEventType,
+    IntegrationProgressLevel,
+} from '@memberjunction/integration-progress-artifacts';
+import { PubSubManager } from '../generic/PubSubManager.js';
+
+/**
+ * The single PubSub topic all integration progress notifications ride. Mirrors
+ * PIPELINE_PROGRESS_TOPIC — one topic, filtered per-subscriber by run/connector/kind.
+ */
+export const INTEGRATION_PROGRESS_TOPIC = 'INTEGRATION_PROGRESS';
+
+/**
+ * Logical channels (the "topic enum" of plan.md §11) a subscriber can scope to.
+ * These map 1:1 onto a subset of {@link IntegrationRunKind} so a UI can subscribe
+ * to, e.g., only sync progress without parsing every notification. Expressed as a
+ * string union (per the union-types-over-enums convention) and surfaced over
+ * GraphQL as a plain String argument/field.
+ */
+export type IntegrationProgressTopic =
+    | 'MetadataRefresh'
+    | 'ConnectorCreation'
+    | 'Sync'
+    | 'RSU';
+
+/**
+ * Maps an {@link IntegrationRunKind} (the vocabulary the emitter writes) onto the
+ * coarser {@link IntegrationProgressTopic} channel a subscriber filters by. Kinds
+ * without a dedicated channel resolve to `undefined` and only match unscoped
+ * subscriptions.
+ */
+const RUN_KIND_TO_TOPIC: Readonly<Record<IntegrationRunKind, IntegrationProgressTopic | undefined>> = {
+    Discovery: 'MetadataRefresh',
+    Enrichment: 'MetadataRefresh',
+    ConnectorCreation: 'ConnectorCreation',
+    SyncRun: 'Sync',
+    RSU: 'RSU',
+    TableCreation: 'RSU',
+    Other: undefined,
+};
+
+/** Resolve the logical channel for a run kind (helper kept tiny + testable). */
+export function IntegrationProgressTopicForKind(kind: IntegrationRunKind): IntegrationProgressTopic | undefined {
+    return RUN_KIND_TO_TOPIC[kind];
+}
+
+/**
+ * A single integration progress notification pushed to the subscription topic.
+ * Carries the structured shape plan.md §11 asks for — the subsystem-specific
+ * `data` payload is serialized into `DataJSON` so the GraphQL field stays a scalar.
+ */
+@ObjectType()
+export class IntegrationProgressNotification {
+    /** The run this event belongs to (matches manifest.runID). */
+    @Field(() => String)
+    RunID: string;
+
+    /** The connector (CompanyIntegration) the run is for, when known. */
+    @Field(() => String, { nullable: true })
+    CompanyIntegrationID?: string;
+
+    /** What kind of run produced this event (IntegrationRunKind, as a string). */
+    @Field(() => String)
+    Kind: string;
+
+    /** The logical channel this notification belongs to (IntegrationProgressTopic). */
+    @Field(() => String, { nullable: true })
+    Topic?: string;
+
+    /** The progress event type (IntegrationProgressEventType, as a string). */
+    @Field(() => String)
+    EventType: string;
+
+    /** Monotonic sequence number within the run. */
+    @Field(() => Int)
+    Seq: number;
+
+    /** Free-form human message (optional). */
+    @Field(() => String, { nullable: true })
+    Message?: string;
+
+    /** Stage name within the run (optional). */
+    @Field(() => String, { nullable: true })
+    Stage?: string;
+
+    /** Severity level (info/warn/error/debug). */
+    @Field(() => String, { nullable: true })
+    Level?: string;
+
+    /** Subsystem-specific structured payload, JSON-serialized. */
+    @Field(() => String, { nullable: true })
+    DataJSON?: string;
+}
+
+/**
+ * Arguments the emitter/pipeline pass to {@link PublishIntegrationProgress}. The
+ * helper derives `Topic` and serializes `Data`, so callers pass the raw event shape.
+ */
+export interface PublishIntegrationProgressArgs {
+    RunID: string;
+    Kind: IntegrationRunKind;
+    EventType: IntegrationProgressEventType;
+    Seq: number;
+    CompanyIntegrationID?: string;
+    Message?: string;
+    Stage?: string;
+    Level?: IntegrationProgressLevel;
+    Data?: Record<string, unknown>;
+}
+
+/** Predicate used by the @Subscription filter — exported so it is unit-testable. */
+export function MatchesIntegrationSubscription(
+    payload: IntegrationProgressNotification,
+    args: { runID?: string; companyIntegrationID?: string; topic?: string }
+): boolean {
+    if (args.runID && payload.RunID !== args.runID) return false;
+    if (args.companyIntegrationID && payload.CompanyIntegrationID !== args.companyIntegrationID) return false;
+    if (args.topic && payload.Topic !== args.topic) return false;
+    return true;
+}
+
+/**
+ * Build the notification payload from publish args. Pure + side-effect free so the
+ * shape (including JSON serialization + topic derivation) can be asserted in tests
+ * without touching PubSub.
+ */
+export function BuildIntegrationProgressNotification(
+    args: PublishIntegrationProgressArgs
+): IntegrationProgressNotification {
+    return {
+        RunID: args.RunID,
+        CompanyIntegrationID: args.CompanyIntegrationID,
+        Kind: args.Kind,
+        Topic: IntegrationProgressTopicForKind(args.Kind),
+        EventType: args.EventType,
+        Seq: args.Seq,
+        Message: args.Message,
+        Stage: args.Stage,
+        Level: args.Level,
+        DataJSON: serializeData(args.Data),
+    };
+}
+
+/** JSON-serialize the subsystem payload, swallowing cyclic/serialization failures. */
+function serializeData(data?: Record<string, unknown>): string | undefined {
+    if (data == null) return undefined;
+    try {
+        return JSON.stringify(data);
+    } catch (e) {
+        LogError(`IntegrationProgressResolver: failed to serialize data payload: ${e}`);
+        return undefined;
+    }
+}
+
+/**
+ * Publish an integration progress event onto the subscription topic. This is the
+ * entry point server-side producers (IntegrationProgressEmitter, pipelines, sync
+ * engine, RSU) call to push live updates to subscribed clients. Uses the shared
+ * PubSubManager — the same infrastructure as PipelineProgress and cache events.
+ *
+ * Returns the published notification (handy for tests / logging); returns
+ * undefined and logs if publishing fails (never throws into the producer path).
+ */
+export function PublishIntegrationProgress(
+    args: PublishIntegrationProgressArgs
+): IntegrationProgressNotification | undefined {
+    try {
+        const notification = BuildIntegrationProgressNotification(args);
+        PubSubManager.Instance.Publish(INTEGRATION_PROGRESS_TOPIC, { ...notification });
+        return notification;
+    } catch (e) {
+        LogError(`PublishIntegrationProgress failed: ${e}`);
+        return undefined;
+    }
+}
+
+@Resolver()
+export class IntegrationProgressResolver {
+    /**
+     * Subscribe to integration progress notifications. With no arguments the
+     * subscriber receives every integration event on this server; pass any of
+     * `runID`, `companyIntegrationID`, or `topic` to scope the stream.
+     */
+    @Subscription(() => IntegrationProgressNotification, {
+        topics: INTEGRATION_PROGRESS_TOPIC,
+        filter: ({ payload, args }: {
+            payload: IntegrationProgressNotification;
+            args: { runID?: string; companyIntegrationID?: string; topic?: string };
+        }) => MatchesIntegrationSubscription(payload, args),
+    })
+    IntegrationProgress(
+        @Root() notification: IntegrationProgressNotification,
+        @Arg('runID', () => String, { nullable: true }) _runID?: string,
+        @Arg('companyIntegrationID', () => String, { nullable: true }) _companyIntegrationID?: string,
+        @Arg('topic', () => String, { nullable: true }) _topic?: string
+    ): IntegrationProgressNotification {
+        return notification;
+    }
+}
+
+export default IntegrationProgressResolver;

package/src/resolvers/MCPResolver.ts

@@ -7,7 +7,7 @@
 
 import { Resolver, Mutation, Query, Subscription, Arg, Ctx, Root, Field, Int, ObjectType, InputType, PubSub, registerEnumType } from 'type-graphql';
 import { PubSubEngine } from 'type-graphql';
-import { LogError, LogStatus, UserInfo, Metadata, RunView } from '@memberjunction/core';
+import { LogError, LogStatus, LogStatusEx, UserInfo, Metadata, RunView } from '@memberjunction/core';
 import {
     MCPClientManager,
     MCPSyncToolsResult,
@@ -705,25 +705,25 @@ export class MCPResolver extends ResolverBase {
 
         try {
             // Check API key scope authorization
-            LogStatus(`MCPResolver: [${ToolName}] Step 1 - Checking API key authorization...`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 1 - Checking API key authorization...`, verboseOnly: true });
             await this.CheckAPIKeyScopeAuthorization('mcp:execute', ConnectionID, ctx.userPayload);
-            LogStatus(`MCPResolver: [${ToolName}] Step 1 complete - Authorization passed (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 1 complete - Authorization passed (${Date.now() - startTime}ms)`, verboseOnly: true });
 
             // Get the MCP client manager instance and ensure it's initialized
-            LogStatus(`MCPResolver: [${ToolName}] Step 2 - Initializing MCP client manager...`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 2 - Initializing MCP client manager...`, verboseOnly: true });
             const manager = MCPClientManager.Instance;
             const publicUrl = this.getPublicUrl();
             await manager.initialize(user, { publicUrl });
-            LogStatus(`MCPResolver: [${ToolName}] Step 2 complete - Manager initialized (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 2 complete - Manager initialized (${Date.now() - startTime}ms)`, verboseOnly: true });
 
             // Connect if not already connected
             const isConnected = manager.isConnected(ConnectionID);
-            LogStatus(`MCPResolver: [${ToolName}] Step 3 - Connection status: ${isConnected ? 'already connected' : 'needs connection'}`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 3 - Connection status: ${isConnected ? 'already connected' : 'needs connection'}`, verboseOnly: true });
             if (!isConnected) {
                 LogStatus(`MCPResolver: [${ToolName}] Connecting to MCP server for connection ${ConnectionID}...`);
                 try {
                     await manager.connect(ConnectionID, { contextUser: user });
-                    LogStatus(`MCPResolver: [${ToolName}] Step 3 complete - Connected (${Date.now() - startTime}ms)`);
+                    LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 3 complete - Connected (${Date.now() - startTime}ms)`, verboseOnly: true });
                 } catch (connectError) {
                     // Check for OAuth authorization required
                     if (connectError instanceof OAuthAuthorizationRequiredError) {
@@ -763,12 +763,16 @@ export class MCPResolver extends ResolverBase {
             }
 
             // Parse input arguments
-            LogStatus(`MCPResolver: [${ToolName}] Step 4 - Parsing input arguments...`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 4 - Parsing input arguments...`, verboseOnly: true });
             let parsedArgs: Record<string, unknown> = {};
             if (InputArgs) {
                 try {
                     parsedArgs = JSON.parse(InputArgs);
-                    LogStatus(`MCPResolver: [${ToolName}] Parsed args: ${JSON.stringify(parsedArgs).substring(0, 200)}...`);
+                    if (configInfo.loggingSettings.graphql.logVariables) {
+                        LogStatus(`MCPResolver: [${ToolName}] Parsed args: ${JSON.stringify(parsedArgs)}`);
+                    } else {
+                        LogStatus(`MCPResolver: [${ToolName}] tool invoked`);
+                    }
                 } catch (parseError) {
                     LogError(`MCPResolver: [${ToolName}] Failed to parse InputArgs: ${parseError}`);
                     return {
@@ -777,18 +781,18 @@ export class MCPResolver extends ResolverBase {
                     };
                 }
             }
-            LogStatus(`MCPResolver: [${ToolName}] Step 4 complete - Args parsed (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 4 complete - Args parsed (${Date.now() - startTime}ms)`, verboseOnly: true });
 
             // Call the tool
-            LogStatus(`MCPResolver: [${ToolName}] Step 5 - Calling tool on connection ${ConnectionID}...`);
-            LogStatus(`MCPResolver: [${ToolName}] Tool ID: ${ToolID}`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 5 - Calling tool on connection ${ConnectionID}...`, verboseOnly: true });
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Tool ID: ${ToolID}`, verboseOnly: true });
             const result: MCPToolCallResult = await manager.callTool(
                 ConnectionID,
                 ToolName,
                 { arguments: parsedArgs },
                 { contextUser: user }
             );
-            LogStatus(`MCPResolver: [${ToolName}] Step 5 complete - Tool call returned (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 5 complete - Tool call returned (${Date.now() - startTime}ms)`, verboseOnly: true });
 
             // Format the result for the response - wrap in object for GraphQLJSONObject
             let formattedResult: Record<string, unknown> | null = null;
@@ -827,7 +831,7 @@ export class MCPResolver extends ResolverBase {
                 formattedResult = result.structuredContent as Record<string, unknown>;
             }
 
-            LogStatus(`MCPResolver: [${ToolName}] Step 6 complete - Result formatted (${Date.now() - startTime}ms)`);
+            LogStatusEx({ message: `MCPResolver: [${ToolName}] Step 6 complete - Result formatted (${Date.now() - startTime}ms)`, verboseOnly: true });
             LogStatus(`MCPResolver: [${ToolName}] Tool execution complete - Success: ${result.success}, Duration: ${result.durationMs}ms, Total time: ${Date.now() - startTime}ms`);
 
             return {

package/src/resolvers/RunAIAgentResolver.ts

@@ -9,6 +9,7 @@ import { AIEngine } from '@memberjunction/aiengine';
 import { ChatMessage, ChatMessageContent } from '@memberjunction/ai';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
+import { startLivenessPulse } from '../generic/FireAndForgetHeartbeat.js';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GetReadWriteProvider } from '../util.js';
 import { SafeJSONParse, UUIDsEqual } from '@memberjunction/global';
@@ -242,6 +243,13 @@ export class RunAIAgentResolver extends ResolverBase {
      */
     private createProgressCallback(pubSub: PubSubEngine, sessionId: string, userPayload: UserPayload, agentRunRef: { current: any }) {
         return (progress: any) => {
+            // Capture the agent run into the ref as soon as any progress event carries it (even
+            // "noise" steps), so the fire-and-forget liveness pulse can read its id/status mid-run
+            // rather than only after RunAgentInConversation returns.
+            if (progress.metadata?.agentRun) {
+                agentRunRef.current = progress.metadata.agentRun;
+            }
+
             // Only publish progress for significant steps (not initialization noise)
             const significantSteps = ['prompt_execution', 'action_execution', 'subagent_execution', 'decision_processing'];
             if (!significantSteps.includes(progress.step)) {
@@ -373,7 +381,10 @@ export class RunAIAgentResolver extends ResolverBase {
         sourceArtifactId?: string,
         sourceArtifactVersionId?: string,
         /** LATENCY OPT #2: Pre-resolved conversationId avoids redundant DB load in AgentRunner */
-        conversationId?: string
+        conversationId?: string,
+        /** Optional external ref the caller can read to observe the agent run as it becomes available
+         *  (used by the fire-and-forget liveness pulse to enrich heartbeats with the run id/status). */
+        runRef?: { current: MJAIAgentRunEntityExtended | null }
     ): Promise<AIAgentRunResult> {
         const startTime = Date.now();
         
@@ -407,8 +418,9 @@ export class RunAIAgentResolver extends ResolverBase {
             // singleton's transaction state with concurrent requests (e.g. conversation deletes).
             const agentRunner = new AgentRunner(p);
 
-            // Track agent run for streaming (use ref to update later)
-            const agentRunRef = { current: null as any };
+            // Track agent run for streaming (use ref to update later). Reuse the caller-supplied
+            // ref when provided so the fire-and-forget liveness pulse can observe the run.
+            const agentRunRef = runRef ?? { current: null as any };
 
             console.log(`🚀 Starting agent execution with sessionId: ${sessionId}`);
 
@@ -1225,12 +1237,23 @@ export class RunAIAgentResolver extends ResolverBase {
         /** LATENCY OPT #2: Pre-resolved conversationId avoids redundant DB load in AgentRunner */
         conversationId?: string
     ): void {
+        // Ref the liveness pulse reads to enrich heartbeats once the run is created.
+        const runRef: { current: MJAIAgentRunEntityExtended | null } = { current: null };
+        const pulse = startLivenessPulse({
+            pubSub,
+            sessionId,
+            resolver: 'RunAIAgentResolver',
+            readStatus: () => runRef.current
+                ? { runId: runRef.current.ID, status: runRef.current.Status }
+                : undefined,
+        });
+
         // Execute in background - errors are handled within, not propagated
         this.executeAIAgent(
             p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub,
             data, payload, undefined, lastRunId, autoPopulateLastRunPayload,
             configurationId, conversationDetailId, createArtifacts, createNotification,
-            sourceArtifactId, sourceArtifactVersionId, conversationId
+            sourceArtifactId, sourceArtifactVersionId, conversationId, runRef
         ).catch((error: unknown) => {
             // Background execution failed unexpectedly (executeAIAgent has its own try-catch,
             // so this would only fire for truly unexpected errors).
@@ -1249,7 +1272,7 @@ export class RunAIAgentResolver extends ResolverBase {
                 result: JSON.stringify({ success: false, errorMessage })
             };
             this.PublishStreamingUpdate(pubSub, errorCompletionData, userPayload);
-        });
+        }).finally(() => pulse.stop());
     }
 
     /**

package/src/resolvers/RunClusterAnalysisResolver.ts

@@ -0,0 +1,249 @@
+import { Resolver, Mutation, Arg, Ctx, ObjectType, InputType, Field, Float, Int } from 'type-graphql';
+import { AppContext } from '../types.js';
+import { LogError, LogStatus, UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetReadWriteProvider } from '../util.js';
+import {
+    ClusteringEngine,
+    EntityDocumentVectorSource,
+    ClusterConfig,
+    ClusterAlgorithm,
+    ClusterDistanceMetric,
+} from '@memberjunction/clustering-engine';
+
+/* ───── GraphQL input ───── */
+
+@InputType()
+export class RunClusterAnalysisInput {
+    @Field({ nullable: true })
+    EntityName?: string;
+
+    @Field({ nullable: true })
+    EntityID?: string;
+
+    @Field({ nullable: true })
+    EntityDocumentID?: string;
+
+    /**
+     * Multi-entity clustering: one or more Entity Document IDs whose vectors are
+     * merged into a single analysis. Takes precedence over EntityDocumentID when
+     * non-empty. All selected docs must share the same embedding model (the engine
+     * hard-blocks mismatches).
+     */
+    @Field(() => [String], { nullable: true })
+    EntityDocumentIDs?: string[];
+
+    /** Legend mode: color points by 'cluster' (default) or 'entity'. */
+    @Field({ nullable: true })
+    ColorBy?: string;
+
+    /** Clustering algorithm: 'kmeans' or 'dbscan'. */
+    @Field({ nullable: true })
+    Algorithm?: string;
+
+    /** Number of clusters for K-Means. */
+    @Field(() => Int, { nullable: true })
+    K?: number;
+
+    /** Epsilon neighbourhood radius for DBSCAN. */
+    @Field(() => Float, { nullable: true })
+    Epsilon?: number;
+
+    /** Minimum points to form a dense region in DBSCAN. */
+    @Field(() => Int, { nullable: true })
+    MinPoints?: number;
+
+    /** Distance metric: 'cosine', 'euclidean' or 'dotproduct'. */
+    @Field({ nullable: true })
+    DistanceMetric?: string;
+
+    /** Maximum number of records to fetch for clustering. */
+    @Field(() => Int, { nullable: true })
+    MaxRecords?: number;
+
+    /** Optional SQL-style filter applied by the vector source. */
+    @Field({ nullable: true })
+    Filter?: string;
+
+    /** When true, runs the optional LLM cluster-naming step. */
+    @Field({ nullable: true })
+    NameClusters?: boolean;
+
+    /** Number of dimensions for the projected layout (2 or 3). Defaults to 2. */
+    @Field(() => Int, { nullable: true })
+    Dimensions?: number;
+
+    /**
+     * When supplied, the result is persisted as an `MJ: Cluster Analysis` row
+     * with this Name and the returned `AnalysisID` is populated.
+     */
+    @Field({ nullable: true })
+    PersistName?: string;
+}
+
+/* ───── GraphQL output ───── */
+
+@ObjectType()
+export class RunClusterAnalysisResult {
+    @Field()
+    Success: boolean;
+
+    @Field({ nullable: true })
+    ErrorMessage?: string;
+
+    /** Number of clusters discovered. */
+    @Field(() => Int)
+    ClusterCount: number;
+
+    /** Number of records that were clustered. */
+    @Field(() => Int)
+    RecordCount: number;
+
+    /** Number of outlier points (DBSCAN only). */
+    @Field(() => Int)
+    OutlierCount: number;
+
+    /** Silhouette score (-1 .. 1). */
+    @Field(() => Float)
+    SilhouetteScore: number;
+
+    /** Wall-clock computation time in milliseconds. */
+    @Field(() => Float)
+    ComputationTimeMs: number;
+
+    /** JSON-serialized {@link ClusterMetrics}. */
+    @Field()
+    MetricsJSON: string;
+
+    /** JSON-serialized array of {@link ClusterInfo}. */
+    @Field()
+    ClustersJSON: string;
+
+    /** JSON-serialized array of {@link ClusterPoint} (can be large). */
+    @Field()
+    PointsJSON: string;
+
+    /** The persisted `MJ: Cluster Analysis` ID when a PersistName was supplied. */
+    @Field({ nullable: true })
+    AnalysisID?: string;
+}
+
+/* ───── Resolver ───── */
+
+@Resolver()
+export class RunClusterAnalysisResolver extends ResolverBase {
+    @Mutation(() => RunClusterAnalysisResult)
+    async RunClusterAnalysis(
+        @Arg('input', () => RunClusterAnalysisInput) input: RunClusterAnalysisInput,
+        @Ctx() context: AppContext = {} as AppContext
+    ): Promise<RunClusterAnalysisResult> {
+        try {
+            const currentUser = this.GetUserFromPayload(context.userPayload);
+            if (!currentUser) {
+                return this.errorResult('Unable to determine current user');
+            }
+
+            // Per-request provider so reads/writes use this user's connection +
+            // security context (multi-user safe), not the process global.
+            const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+            const config = this.buildConfig(input);
+            const engine = new ClusteringEngine();
+            const vectorSource = new EntityDocumentVectorSource(currentUser, provider);
+
+            LogStatus(
+                `RunClusterAnalysis: algorithm=${config.Algorithm} entity=${config.EntityName ?? config.EntityID ?? config.EntityDocumentID}`
+            );
+
+            const result = await engine.RunPipeline(config, vectorSource, currentUser);
+
+            let analysisID: string | undefined;
+            if (input.PersistName && input.PersistName.trim().length > 0) {
+                analysisID = await this.persistAnalysis(engine, result, config, input.PersistName.trim(), currentUser, provider);
+            }
+
+            return {
+                Success: true,
+                ClusterCount: result.Metrics.ClusterCount,
+                RecordCount: result.Metrics.RecordCount,
+                OutlierCount: result.Metrics.OutlierCount,
+                SilhouetteScore: result.Metrics.SilhouetteScore,
+                ComputationTimeMs: result.Metrics.ComputationTimeMs,
+                MetricsJSON: JSON.stringify(result.Metrics),
+                ClustersJSON: JSON.stringify(result.Clusters),
+                PointsJSON: JSON.stringify(result.Points),
+                AnalysisID: analysisID,
+            };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`RunClusterAnalysis mutation failed: ${msg}`);
+            return this.errorResult(msg);
+        }
+    }
+
+    /** Build a {@link ClusterConfig} from the GraphQL input, applying defaults. */
+    private buildConfig(input: RunClusterAnalysisInput): ClusterConfig {
+        return {
+            EntityName: input.EntityName ?? '',
+            EntityID: input.EntityID ?? '',
+            EntityDocumentID: input.EntityDocumentID ?? '',
+            EntityDocumentIDs: (input.EntityDocumentIDs ?? []).filter((id) => !!id && id.trim().length > 0),
+            ColorBy: input.ColorBy === 'entity' ? 'entity' : 'cluster',
+            Algorithm: this.normalizeAlgorithm(input.Algorithm),
+            K: input.K ?? 4,
+            Epsilon: input.Epsilon ?? 0.3,
+            MinPoints: input.MinPoints ?? 3,
+            DistanceMetric: this.normalizeMetric(input.DistanceMetric),
+            MaxRecords: input.MaxRecords ?? 500,
+            Filter: input.Filter ?? '',
+            NameClusters: input.NameClusters ?? false,
+            Dimensions: input.Dimensions === 3 ? 3 : 2,
+        };
+    }
+
+    /** Coerce a raw algorithm string to a supported {@link ClusterAlgorithm}. */
+    private normalizeAlgorithm(value: string | undefined): ClusterAlgorithm {
+        return value?.toLowerCase() === 'dbscan' ? 'dbscan' : 'kmeans';
+    }
+
+    /** Coerce a raw metric string to a supported {@link ClusterDistanceMetric}. */
+    private normalizeMetric(value: string | undefined): ClusterDistanceMetric {
+        const v = value?.toLowerCase();
+        if (v === 'euclidean' || v === 'dotproduct') {
+            return v;
+        }
+        return 'cosine';
+    }
+
+    /** Persist the result and return the new analysis ID (or undefined on failure). */
+    private async persistAnalysis(
+        engine: ClusteringEngine,
+        result: Awaited<ReturnType<ClusteringEngine['RunPipeline']>>,
+        config: ClusterConfig,
+        persistName: string,
+        currentUser: UserInfo,
+        provider?: IMetadataProvider
+    ): Promise<string | undefined> {
+        const owner = { Name: persistName, UserID: currentUser.ID };
+        const savedID = await engine.SaveAnalysis(result, config, owner, currentUser, provider);
+        if (!savedID) {
+            LogError(`RunClusterAnalysis: failed to persist analysis "${persistName}".`);
+            return undefined;
+        }
+        return savedID;
+    }
+
+    private errorResult(message: string): RunClusterAnalysisResult {
+        return {
+            Success: false,
+            ErrorMessage: message,
+            ClusterCount: 0,
+            RecordCount: 0,
+            OutlierCount: 0,
+            SilhouetteScore: 0,
+            ComputationTimeMs: 0,
+            MetricsJSON: '{}',
+            ClustersJSON: '[]',
+            PointsJSON: '[]',
+        };
+    }
+}