feat(iwooos): add wazuh executor handoff runway

apps/api/src/services/iwooos_security_tool_closure_readback.py

@@ -19,6 +19,9 @@ from src.services.iwooos_security_operating_system import (
 from src.services.iwooos_wazuh_allowlisted_check_mode_dry_run import (
     load_latest_iwooos_wazuh_allowlisted_check_mode_dry_run,
 )
+from src.services.iwooos_wazuh_controlled_executor_handoff import (
+    load_latest_iwooos_wazuh_controlled_executor_handoff,
+)
 from src.services.iwooos_wazuh_fim_vulnerability_alert_verifier import (
     load_latest_iwooos_wazuh_fim_vulnerability_alert_verifier,
 )
@@ -66,6 +69,11 @@ def load_latest_iwooos_security_tool_closure_readback(
             alert_receipt_readback=alert_receipt_readback
         )
     )
+    wazuh_controlled_executor_handoff = (
+        load_latest_iwooos_wazuh_controlled_executor_handoff(
+            alert_receipt_readback=alert_receipt_readback
+        )
+    )
 
     source_payloads = [
         coverage,
@@ -77,6 +85,7 @@ def load_latest_iwooos_security_tool_closure_readback(
         dry_run,
         wazuh_verifier,
         wazuh_incident_response_closure,
+        wazuh_controlled_executor_handoff,
     ]
     _require_runtime_boundaries(source_payloads)
 
@@ -89,8 +98,9 @@ def load_latest_iwooos_security_tool_closure_readback(
         "owner_review": _summary(owner_review),
         "dry_run": _summary(dry_run),
         "wazuh_verifier": _summary(wazuh_verifier),
-        "wazuh_incident_response_closure": _summary(
-            wazuh_incident_response_closure
+        "wazuh_incident_response_closure": _summary(wazuh_incident_response_closure),
+        "wazuh_controlled_executor_handoff": _summary(
+            wazuh_controlled_executor_handoff
         ),
     }
     tracks = _tool_tracks(source_summaries)
@@ -145,6 +155,7 @@ def load_latest_iwooos_security_tool_closure_readback(
             *dry_run.get("source_refs", []),
             *wazuh_verifier.get("source_refs", []),
             *wazuh_incident_response_closure.get("source_refs", []),
+            *wazuh_controlled_executor_handoff.get("source_refs", []),
         ],
     }
 
@@ -289,7 +300,9 @@ def _tool_tracks(source_summaries: dict[str, dict[str, Any]]) -> list[dict[str,
             required_signal_count=4,
             next_executable_action="stage_rule_dry_run_event_redaction_and_wazuh_correlation",
             required_verifier="runtime_detection_event_post_verifier",
-            source_refs=["docs/security/monitoring-alerting-observability-inventory.snapshot.json"],
+            source_refs=[
+                "docs/security/monitoring-alerting-observability-inventory.snapshot.json"
+            ],
         ),
         _track(
             track_id="web_api_dast",
@@ -311,7 +324,9 @@ def _tool_tracks(source_summaries: dict[str, dict[str, Any]]) -> list[dict[str,
             required_signal_count=4,
             next_executable_action="normalize_wazuh_alertmanager_app_events_into_review_cards",
             required_verifier="sigma_ocsf_event_mapping_regression_verifier",
-            source_refs=["docs/security/iwooos-security-operating-system.snapshot.json"],
+            source_refs=[
+                "docs/security/iwooos-security-operating-system.snapshot.json"
+            ],
         ),
         _track(
             track_id="ai_agent_controlled_apply",
@@ -351,7 +366,11 @@ def _track(
 ) -> dict[str, Any]:
     ready_count = max(min(ready_signal_count, required_signal_count), 0)
     missing_count = max(required_signal_count - ready_count, 0)
-    source_readiness_percent = int(round((ready_count / required_signal_count) * 100)) if required_signal_count else 0
+    source_readiness_percent = (
+        int(round((ready_count / required_signal_count) * 100))
+        if required_signal_count
+        else 0
+    )
     source_ready = missing_count == 0
     if runtime_closed:
         runtime_closure_state = "runtime_closed"
@@ -404,6 +423,9 @@ def _summary_rollup(
     wazuh_incident_response_closure = source_summaries[
         "wazuh_incident_response_closure"
     ]
+    wazuh_controlled_executor_handoff = source_summaries[
+        "wazuh_controlled_executor_handoff"
+    ]
 
     expected_hosts = max(
         _int(managed_hosts.get("expected_host_scope_count")),
@@ -425,20 +447,18 @@ def _summary_rollup(
         1 for track in tracks if track.get("runtime_closed") is True
     )
     source_readiness_percent = (
-        int(round((total_ready / total_required) * 100))
-        if total_required
-        else 0
+        int(round((total_ready / total_required) * 100)) if total_required else 0
     )
     runtime_closure_percent = (
-        int(round((runtime_closed_track_count / len(tracks)) * 100))
-        if tracks
-        else 0
+        int(round((runtime_closed_track_count / len(tracks)) * 100)) if tracks else 0
     )
 
     return {
         "source_readback_count": len(source_summaries),
         "tool_track_count": len(tracks),
-        "p0_tool_track_count": sum(1 for track in tracks if track.get("priority") == "P0"),
+        "p0_tool_track_count": sum(
+            1 for track in tracks if track.get("priority") == "P0"
+        ),
         "source_ready_tool_track_count": source_ready_track_count,
         "closed_tool_track_count": runtime_closed_track_count,
         "partial_tool_track_count": sum(
@@ -459,7 +479,9 @@ def _summary_rollup(
         "tool_closure_percent": runtime_closure_percent,
         "wazuh_expected_host_scope_count": expected_hosts,
         "wazuh_manager_registry_accepted_count": accepted_hosts,
-        "wazuh_registry_complete_count": 1 if expected_hosts > 0 and accepted_hosts >= expected_hosts else 0,
+        "wazuh_registry_complete_count": (
+            1 if expected_hosts > 0 and accepted_hosts >= expected_hosts else 0
+        ),
         "wazuh_fim_vulnerability_alert_closed_count": _int(
             wazuh_verifier.get("wazuh_fim_vulnerability_alert_closed_count")
         ),
@@ -469,9 +491,7 @@ def _summary_rollup(
             )
         ),
         "wazuh_fim_vulnerability_alert_runtime_closed_count": _int(
-            wazuh_verifier.get(
-                "wazuh_fim_vulnerability_alert_runtime_closed_count"
-            )
+            wazuh_verifier.get("wazuh_fim_vulnerability_alert_runtime_closed_count")
         ),
         "wazuh_fim_vulnerability_alert_verifier_ready_count": _int(
             wazuh_verifier.get("wazuh_fim_vulnerability_alert_verifier_ready_count")
@@ -500,6 +520,30 @@ def _summary_rollup(
                 "wazuh_incident_response_runtime_closed_count"
             )
         ),
+        "wazuh_controlled_executor_handoff_preview_ready_count": _int(
+            wazuh_controlled_executor_handoff.get(
+                "controlled_executor_handoff_preview_ready_count"
+            )
+        ),
+        "wazuh_controlled_executor_route_ready_count": _int(
+            wazuh_controlled_executor_handoff.get(
+                "controlled_executor_route_ready_count"
+            )
+        ),
+        "wazuh_controlled_executor_post_verifier_binding_count": _int(
+            wazuh_controlled_executor_handoff.get("post_action_verifier_binding_count")
+        ),
+        "wazuh_controlled_executor_learning_writeback_contract_count": _int(
+            wazuh_controlled_executor_handoff.get("learning_writeback_contract_count")
+        ),
+        "wazuh_controlled_executor_dispatch_enabled_count": _int(
+            wazuh_controlled_executor_handoff.get(
+                "bounded_executor_dispatch_enabled_count"
+            )
+        ),
+        "wazuh_controlled_executor_dispatch_count": _int(
+            wazuh_controlled_executor_handoff.get("controlled_executor_dispatch_count")
+        ),
         "alert_receipt_observed_count": _int(
             security_os.get("alert_receipt_observed_count")
         ),
@@ -543,6 +587,9 @@ def _next_executable_queue(
     wazuh_incident_response_closure = source_summaries[
         "wazuh_incident_response_closure"
     ]
+    wazuh_controlled_executor_handoff = source_summaries[
+        "wazuh_controlled_executor_handoff"
+    ]
     controlled_apply = source_summaries["controlled_apply"]
     dry_run = source_summaries["dry_run"]
     expected_hosts = max(
@@ -562,11 +609,7 @@ def _next_executable_queue(
         > 0
     )
     runtime_closed = (
-        _int(
-            wazuh_verifier.get(
-                "wazuh_fim_vulnerability_alert_runtime_closed_count"
-            )
-        )
+        _int(wazuh_verifier.get("wazuh_fim_vulnerability_alert_runtime_closed_count"))
         > 0
     )
     same_run_candidate_ready = (
@@ -618,9 +661,7 @@ def _next_executable_queue(
                 wazuh_incident_response_closure.get("same_run_required_stage_count")
             ),
             "same_run_source_stage_ready_count": _int(
-                wazuh_incident_response_closure.get(
-                    "same_run_source_stage_ready_count"
-                )
+                wazuh_incident_response_closure.get("same_run_source_stage_ready_count")
             ),
             "same_run_closure_candidate_ready_count": _int(
                 wazuh_incident_response_closure.get(
@@ -631,6 +672,17 @@ def _next_executable_queue(
                 "/api/v1/iwooos/wazuh-incident-response-closure/"
                 "validate-incident-response-packet"
             ),
+            "controlled_executor_handoff_readback_endpoint": (
+                "/api/v1/iwooos/wazuh-controlled-executor-handoff-readback"
+            ),
+            "controlled_executor_handoff_preview_endpoint": (
+                "/api/v1/iwooos/wazuh-controlled-executor-handoff/preview"
+            ),
+            "controlled_executor_handoff_preview_ready_count": _int(
+                wazuh_controlled_executor_handoff.get(
+                    "controlled_executor_handoff_preview_ready_count"
+                )
+            ),
             "next_gate_after_packet_acceptance": (
                 "route_to_iwooos_controlled_executor_for_bounded_execution_and_post_verifier_writeback"
             ),
@@ -687,12 +739,12 @@ def _require_runtime_boundaries(payloads: list[dict[str, Any]]) -> None:
         summary = _summary(payload)
         for key in _REQUIRED_ZERO_SUMMARY_KEYS:
             if key in summary and _int(summary.get(key)) != 0:
-                raise ValueError(f"{payload.get('schema_version')}: summary.{key} must remain 0")
+                raise ValueError(
+                    f"{payload.get('schema_version')}: summary.{key} must remain 0"
+                )
         boundaries = payload.get("boundaries")
         if isinstance(boundaries, dict):
-            for key in (
-                "secret_value_collection_allowed",
-            ):
+            for key in ("secret_value_collection_allowed",):
                 if key in boundaries and boundaries.get(key) is not False:
                     raise ValueError(
                         f"{payload.get('schema_version')}: boundaries.{key} must remain false"
@@ -711,6 +763,9 @@ def _boundary_markers(summary: dict[str, Any]) -> list[str]:
         f"iwooos_security_tool_closure_alert_receipt_accepted_count={summary['alert_receipt_accepted_count']}",
         "iwooos_security_tool_closure_controlled_apply_policy_active=true",
         f"iwooos_security_tool_closure_controlled_apply_candidate_ready_count={summary['controlled_apply_candidate_ready_count']}",
+        f"iwooos_wazuh_controlled_executor_handoff_preview_ready_count={summary['wazuh_controlled_executor_handoff_preview_ready_count']}",
+        f"iwooos_wazuh_controlled_executor_dispatch_enabled_count={summary['wazuh_controlled_executor_dispatch_enabled_count']}",
+        f"iwooos_wazuh_controlled_executor_dispatch_count={summary['wazuh_controlled_executor_dispatch_count']}",
         "owner_review_required_for_low_medium_high=false",
         "runtime_execution_performed=false",
         "secret_value_collection_allowed=false",