Add requestBooleanFlag helper and enhance session synchronization logic

- Introduce `requestBooleanFlag` method for consistent boolean parameter handling with default values.
- Add `activate_machine` and `sync_relay_state` parameters to `synchronizeSession` for more flexible relay and machine activation control.
- Update methods, routes, and tests to integrate the new session synchronization parameters effectively.
- Enhance debugging support with additional metadata in simulation and payload captures.

services/nginx/app/modules/selfserve/classes/selfserve_studio_graph.php

@@ -394,6 +394,73 @@ class selfserve_studio_graph
         return $validation;
     }
 
+    /**
+     * @param array<string,mixed> $payload
+     * @param array<string,bool> $permissions
+     * @return array<string,mixed>
+     */
+    public function simulateGraph(int $departmentId, array $payload, ?int $userId = null, array $permissions = []): array
+    {
+        $laneId = (int)($payload['lane_id'] ?? 0);
+        if ($laneId <= 0) {
+            throw new \RuntimeException('lane_id is required for studio simulation.');
+        }
+
+        $configSource = strtolower(trim((string)($payload['config_source'] ?? 'draft')));
+        if (!in_array($configSource, ['draft', 'published'], true)) {
+            $configSource = 'draft';
+        }
+
+        $versioning = new selfserve_config_versioning();
+        if ($configSource === 'published') {
+            $version = $versioning->getPublishedConfig($departmentId);
+            $config = is_array($version['config'] ?? null) ? (array)$version['config'] : $versioning->snapshotLegacyConfig($departmentId);
+            $versionId = isset($version['version_id']) ? (int)$version['version_id'] : null;
+        } else {
+            $version = $versioning->ensureDraftFromLegacy($departmentId, $userId, false);
+            $config = is_array($version['config'] ?? null) ? (array)$version['config'] : $versioning->snapshotLegacyConfig($departmentId);
+            $versionId = isset($version['id']) ? (int)$version['id'] : null;
+        }
+
+        $includeHardware = filter_var($payload['include_hardware'] ?? true, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
+        $includeHardware = $includeHardware !== false;
+        $gatewayWorkspace = ($includeHardware && ($permissions['modules_shelly_config'] ?? false))
+            ? $this->buildGatewayWorkspace($departmentId)
+            : [
+                'gateways' => [],
+                'relays' => [],
+                'lanes' => [],
+                'issues' => [],
+                'actions' => [],
+                'restricted' => !$includeHardware ? false : true,
+            ];
+        $lookups = $this->buildLookups($departmentId, $config, $gatewayWorkspace);
+        $graph = $this->buildGraphFromConfig($config, [
+            'department_id' => $departmentId,
+            'lookups' => $lookups,
+            'gateway_workspace' => $gatewayWorkspace,
+        ]);
+
+        return (new selfserve_wash_flow())->previewStudioSimulation(
+            $departmentId,
+            $laneId,
+            (string)($payload['reg'] ?? ''),
+            array_key_exists('customer_number', $payload) ? $this->nullableInt($payload['customer_number']) : null,
+            array_key_exists('vehicle_type_id', $payload) ? $this->nullableInt($payload['vehicle_type_id']) : null,
+            [
+                'mode' => 'full_dry_run',
+                'config_source' => $configSource,
+                'config_payload' => $config,
+                'config_version_id' => $versionId,
+                'answer_overrides' => is_array($payload['answer_overrides'] ?? null) ? (array)$payload['answer_overrides'] : [],
+                'include_hardware' => $includeHardware,
+                'lookups' => $lookups,
+                'gateway_workspace' => $gatewayWorkspace,
+                'graph' => $graph,
+            ],
+        );
+    }
+
     /**
      * @param array<string,mixed> $payload
      * @return array<string,mixed>

services/nginx/app/modules/selfserve/traits/selfserve_lane_relay_controller_t.php

@@ -260,6 +260,33 @@ trait selfserve_lane_relay_controller_t
         ];
     }
 
+    /**
+     * Persist the services currently visible to the user without mutating hardware.
+     *
+     * The user wash start flow calls this before the user confirms lane and wash type.
+     * Hardware activation remains owned by START / explicit relay endpoints.
+     *
+     * @param array<int,mixed> $allowedServices
+     * @return array{
+     *   machine_visible: bool,
+     *   relay_action: string,
+     *   relay_target_on: bool
+     * }
+     */
+    public function setAllowedServicesFromVisibleTasks(array $allowedServices): array
+    {
+        $normalizedServices = $this->normalizeVisibleServiceNames($allowedServices);
+        $this->setLaneCache($this->id, self::CACHE_SELFSERVE_LANE_KEY_ALLOWED_SERVICES, $normalizedServices);
+
+        $machineVisible = in_array(selfserve_lane_services::MACHINE->name, $normalizedServices, true);
+
+        return [
+            'machine_visible' => $machineVisible,
+            'relay_action' => 'cache_only',
+            'relay_target_on' => $machineVisible,
+        ];
+    }
+
     /**
      * @param array<int,mixed> $services
      * @return string[]