chore(compose): rename convergence.go, whose convergence engine no longer exists

pkg/compose/create.go

@@ -659,7 +659,7 @@ func defaultNetworkSettings(project *types.Project,
 	// in the network configuration instead of connecting the container to each extra
 	// network individually after creation.
 	// For older API versions, extra networks are connected via NetworkConnect after
-	// container creation (see createMobyContainer in convergence.go).
+	// container creation (see createMobyContainer in service_containers.go).
 	if !versions.LessThan(version, apiVersion144) {
 		for _, networkKey := range serviceNetworks {
 			epSettings, err := createEndpointSettings(project, service, serviceIndex, networkKey, links, useNetworkAliases)

pkg/compose/reconcile.go

@@ -716,7 +716,7 @@ func (r *reconciler) reconcileService(service types.ServiceConfig) error {
 		// Container is up-to-date
 		switch oc.State {
 		case container.StateRunning, container.StateCreated, container.StateRestarting, container.StateExited:
-			// Nothing to do (exited containers are left as-is, matching convergence.go behavior)
+			// Nothing to do (exited containers are left as-is, matching service_containers.go behavior)
 		default:
 			// Any other state (paused, dead, ...): attempt to (re)start
 			lastNode = r.plan.addNode(Operation{
@@ -1009,7 +1009,7 @@ func (r *reconciler) infrastructureDeps(service types.ServiceConfig) []*PlanNode
 	return deps
 }
 
-// sortContainers sorts containers the same way as convergence.go:138-160:
+// sortContainers sorts containers the same way as the start path in service_containers.go:
 // obsolete first, then by container number descending, then reversed.
 //
 // mustRecreate is evaluated once per container before sorting to avoid

pkg/compose/reconcile_test.go

@@ -1242,7 +1242,7 @@ func TestReconcileContainers_ExitedIsNoop(t *testing.T) {
 
 	plan, err := reconcile(t.Context(), project, observed, defaultReconcileOptions(), noPrompt)
 	assert.NilError(t, err)
-	// Exited containers are left as-is, matching convergence.go:199 behavior
+	// Exited containers are left as-is: starting containers is not the plan engine's job
 	assert.Assert(t, plan.IsEmpty())
 }
 

pkg/compose/convergence.go → pkg/compose/service_containers.go

@@ -38,17 +38,23 @@ import (
 	"github.com/docker/compose/v5/pkg/api"
 )
 
+// This file gathers the per-service container helpers shared by both
+// lifecycle engines: the plan-based reconciler (reconcile.go, entered through
+// create/up) and the imperative dependency-ordered engine (dependencies.go,
+// used by start/stop/restart/down). It covers container naming, resolution of
+// service references (volumes_from, network_mode/ipc/pid, links), dependency
+// waiting, container creation through the Docker API, and service startup.
+
 const (
 	doubledContainerNameWarning = "WARNING: The %q service is using the custom container name %q. " +
 		"Docker requires each container to have a unique name. " +
 		"Remove the custom name to scale the service"
 )
 
-// convergence manages service's container lifecycle.
-// Based on initially observed state, it reconciles the existing container with desired state, which might include
-// re-creating container, adding or removing replicas, or starting stopped containers.
-// Cross services dependencies are managed by creating services in expected order and updating `service:xx` reference
-// when a service has converged, so dependent ones can be managed with resolved containers references.
+// getScale returns the number of replicas the service must run. A service
+// pinned to a custom container_name cannot scale beyond one replica, as every
+// container needs a distinct name: this is rejected here rather than at
+// container-creation time.
 func getScale(config types.ServiceConfig) (int, error) {
 	scale := config.GetScale()
 	if scale > 1 && config.ContainerName != "" {