feat(telegram): expose alert learning writeback refs

apps/api/tests/test_awooop_operator_timeline_labels.py

@@ -973,6 +973,24 @@ def test_ai_alert_card_delivery_item_uses_metadata_without_raw_content() -> None
     assert item["runtime_write_gate_count"] == 1
     assert item["runtime_write_allowed"] is True
     assert item["delivery_receipt_readback_required"] is True
+    assert item["learning_writeback_ready"] is True
+    assert item["learning_writeback_status"] == "ready"
+    assert item["learning_writeback_refs"]["km_entry_ref"] == (
+        "km://awoooi/telegram-ai-alert-card/wazuh_dashboard_api_readback_degraded"
+    )
+    assert item["learning_writeback_refs"]["playbook_candidate_ref"] == (
+        "playbook://awoooi/telegram-ai-alert-card/"
+        "siem_observability_readback_degraded/wazuh_dashboard_api"
+    )
+    assert item["learning_writeback_refs"]["rag_chunk_ref"].startswith(
+        "rag://awoooi/telegram-ai-alert-card/"
+    )
+    assert item["learning_writeback_refs"]["mcp_evidence_ref"].endswith(
+        "66cdb6ad-46a4-48f5-9d3b-b1ac9c0b2e92"
+    )
+    assert item["learning_writeback_refs"]["post_verifier_ref"].endswith(
+        "5c0306e0-591a-5445-9a33-80f499426b38"
+    )
     assert item["source_refs"]["alert_ids"] == [
         "wazuh_dashboard_api_readback_degraded"
     ]
@@ -991,6 +1009,7 @@ def test_ai_alert_card_delivery_summary_keeps_no_false_green_status() -> None:
             "shadow_total": 0,
             "delivery_receipt_required_total": 2,
             "runtime_write_gate_open_count": 1,
+            "learning_writeback_ready_total": 1,
             "latest_sent_at": datetime(2026, 6, 25, 9, 40, 5),
             "latest_queued_at": datetime(2026, 6, 25, 9, 40, 0),
         },
@@ -1004,6 +1023,16 @@ def test_ai_alert_card_delivery_summary_keeps_no_false_green_status() -> None:
     assert summary["delivery_receipt_required_total"] == 2
     assert summary["runtime_write_gate_open_count"] == 1
     assert summary["runtime_write_allowed"] is True
+    assert summary["learning_writeback_ready_total"] == 1
+    assert summary["learning_writeback_missing_total"] == 1
+    assert summary["km_writeback_ref_ready_total"] == 1
+    assert summary["playbook_writeback_ref_ready_total"] == 1
+    assert summary["rag_chunk_ref_ready_total"] == 1
+    assert summary["mcp_evidence_ref_ready_total"] == 1
+    assert summary["post_verifier_ref_ready_total"] == 1
+    assert summary["learning_writeback_next_action"] == (
+        "ensure_ai_alert_cards_include_event_type_lane_and_delivery_receipt"
+    )
     assert summary["production_write_count"] == 0
 
 
@@ -1032,6 +1061,45 @@ def test_list_ai_alert_cards_response_preserves_delivery_metadata() -> None:
                 "candidate_only": False,
                 "controlled_playbook_queue": True,
                 "delivery_receipt_readback_required": True,
+                "learning_writeback_ready": True,
+                "learning_writeback_status": "ready",
+                "learning_writeback_refs": {
+                    "schema_version": "ai_alert_card_learning_writeback_refs_v1",
+                    "status": "ready",
+                    "work_item_id": "CIR-P0-TG-001",
+                    "receipt_source": "awooop_outbound_message",
+                    "receipt_id": str(message_id),
+                    "run_id": str(run_id),
+                    "project_id": "awoooi",
+                    "km_entry_ref": (
+                        "km://awoooi/telegram-ai-alert-card/"
+                        "wazuh_dashboard_api_readback_degraded"
+                    ),
+                    "playbook_candidate_ref": (
+                        "playbook://awoooi/telegram-ai-alert-card/"
+                        "siem_observability_readback_degraded/"
+                        "wazuh_dashboard_api"
+                    ),
+                    "rag_chunk_ref": (
+                        "rag://awoooi/telegram-ai-alert-card/"
+                        "wazuh_dashboard_api_readback_degraded/"
+                        f"{message_id}"
+                    ),
+                    "mcp_evidence_ref": (
+                        "mcp://awoooi/awooop_outbound_message/"
+                        f"{message_id}"
+                    ),
+                    "post_verifier_ref": (
+                        "verifier://awoooi/telegram-alert-delivery-receipt/"
+                        f"{run_id}"
+                    ),
+                    "source_fingerprints": [],
+                    "alert_ids": ["wazuh_dashboard_api_readback_degraded"],
+                    "missing_required_fields": [],
+                    "production_write_performed": False,
+                    "runtime_send_performed": False,
+                    "next_action": "none",
+                },
                 "source_refs": {
                     "alert_ids": ["wazuh_dashboard_api_readback_degraded"],
                 },
@@ -1061,6 +1129,14 @@ def test_list_ai_alert_cards_response_preserves_delivery_metadata() -> None:
             "delivery_receipt_required_total": 1,
             "runtime_write_gate_open_count": 1,
             "runtime_write_allowed": True,
+            "learning_writeback_ready_total": 1,
+            "learning_writeback_missing_total": 0,
+            "km_writeback_ref_ready_total": 1,
+            "playbook_writeback_ref_ready_total": 1,
+            "rag_chunk_ref_ready_total": 1,
+            "mcp_evidence_ref_ready_total": 1,
+            "post_verifier_ref_ready_total": 1,
+            "learning_writeback_next_action": "none",
             "latest_sent_at": datetime(2026, 6, 25, 9, 40, 5),
             "latest_queued_at": datetime(2026, 6, 25, 9, 40, 0),
             "production_write_count": 0,
@@ -1072,7 +1148,12 @@ def test_list_ai_alert_cards_response_preserves_delivery_metadata() -> None:
         "wazuh_dashboard_api_readback_degraded"
     )
     assert dumped["items"][0]["runtime_write_allowed"] is True
+    assert dumped["items"][0]["learning_writeback_ready"] is True
+    assert dumped["items"][0]["learning_writeback_refs"]["work_item_id"] == (
+        "CIR-P0-TG-001"
+    )
     assert dumped["summary"]["delivery_receipt_required_total"] == 1
+    assert dumped["summary"]["learning_writeback_ready_total"] == 1
     assert dumped["summary"]["production_write_count"] == 0
 
 

apps/api/tests/test_telegram_alert_ai_automation_matrix_api.py

@@ -52,7 +52,10 @@ def test_telegram_alert_ai_automation_matrix_loader_returns_gap_matrix():
     assert summary["secret_value_read_count"] == 0
     assert summary["runtime_write_performed_count"] == 0
     assert summary["ai_alert_card_delivery_readback_endpoint_count"] == 1
-    assert summary["next_priority_action_id"] == "bind_ai_alert_cards_to_learning_writeback"
+    assert summary["ai_alert_card_learning_writeback_refs_count"] == 1
+    assert summary["next_priority_action_id"] == (
+        "promote_telegram_alert_learning_refs_to_km_rag_mcp_registry"
+    )
 
     matrix = {item["surface_id"]: item for item in payload["matrix"]}
     assert matrix["telegram_gateway_ai_alert_cards"]["status"] == (
@@ -75,6 +78,9 @@ def test_telegram_alert_ai_automation_matrix_loader_returns_gap_matrix():
     assert matrix["telegram_ai_alert_card_delivery_readback_endpoint"][
         "db_or_log_receipt"
     ] == "ready_awooop_outbound_message_query"
+    assert matrix["telegram_ai_alert_card_delivery_readback_endpoint"][
+        "learning_writeback"
+    ] == "ready_delivery_receipt_summary_and_learning_writeback_refs"
 
     assert payload["direct_send_gap_refs"] == []
     assert not any(
@@ -108,7 +114,9 @@ def test_telegram_matrix_source_contract_supports_container_layout(tmp_path):
         encoding="utf-8",
     )
     (tmp_path / "src/api/v1/platform/operator_runs.py").write_text(
-        '"/runs/ai-alert-cards"\n',
+        '"/runs/ai-alert-cards"\n'
+        "learning_writeback_refs\n"
+        "learning_writeback_ready_total\n",
         encoding="utf-8",
     )
 
@@ -120,6 +128,8 @@ def test_telegram_matrix_source_contract_supports_container_layout(tmp_path):
     assert proof["outbound_message_model_present"] is True
     assert proof["ai_alert_card_delivery_readback_endpoint_present"] is True
     assert proof["ai_alert_card_delivery_readback_endpoint_count"] == 1
+    assert proof["ai_alert_card_learning_writeback_refs_present"] is True
+    assert proof["ai_alert_card_learning_writeback_refs_count"] == 1
 
 
 def test_telegram_alert_ai_automation_matrix_endpoint_returns_readback():