From a902c951552c68dcf35645c54c015d259427fba2 Mon Sep 17 00:00:00 2001
From: "Tachikoma (Codex GPT-5)" <tachikoma@aklabs.net>
Date: Sun, 2 Aug 2026 23:52:04 -0400
Subject: [PATCH] Annotate intentional handler fallthrough

Co-authored-by: Andrew Kesterson <andrew@aklabs.net>
---
 CMakeLists.txt         |  8 ++++++++
 include/akerror.tmpl.h | 13 +++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 69dbe30..d4495af 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -263,6 +263,14 @@ foreach(_test IN LISTS AKERR_TESTS)
     endif()
 endforeach()
 
+# HANDLE_GROUP deliberately enters the next case label. Keep that public macro
+# compiling with the warning enabled, so a future macro edit cannot restore the
+# warning for consumers which adopt -Wextra.
+if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+    target_compile_options(test_err_handle_group PRIVATE
+                           -Werror=implicit-fallthrough)
+endif()
+
 set_tests_properties(
     ${AKERR_WILL_FAIL_TESTS}
     PROPERTIES WILL_FAIL TRUE
diff --git a/include/akerror.tmpl.h b/include/akerror.tmpl.h
index dad4c45..ede8fcc 100644
--- a/include/akerror.tmpl.h
+++ b/include/akerror.tmpl.h
@@ -391,6 +391,18 @@ akerr_ErrorContext AKERR_NOIGNORE *__akerr_copy_string(char *destination, int ca
  * Defines for the ATTEMPT/CATCH/CLEANUP/PROCESS/HANDLE/FINISH process
  */
 
+/*
+ * HANDLE_GROUP deliberately enters the next case label. GCC and clang both
+ * understand this spelling in the C modes supported by libakerror. Other
+ * compilers keep the established control flow without receiving an attribute
+ * they do not implement.
+ */
+#if defined(__GNUC__) || defined(__clang__)
+#define AKERR_FALLTHROUGH __attribute__((fallthrough));
+#else
+#define AKERR_FALLTHROUGH
+#endif
+
 #define ATTEMPT					\
     switch ( 0 ) {				\
     case 0:					\
@@ -443,6 +455,7 @@ akerr_ErrorContext AKERR_NOIGNORE *__akerr_copy_string(char *destination, int ca
     __err_context->handled = true;
 
 #define HANDLE_GROUP(__err_context, __err_status)			\
+    AKERR_FALLTHROUGH					\
     case __err_status:							\
     __err_context->stacktracebufptr = (char *)&__err_context->stacktracebuf; \
     __err_context->handled = true;