From 87923661a0dfe801f8694a712cd904bc872fafe5 Mon Sep 17 00:00:00 2001
From: Ronald Caesar <github43132@proton.me>
Date: Wed, 17 Jun 2026 01:47:03 -0400
Subject: [PATCH] engine: reorganize error enum values

Signed-off-by: Ronald Caesar <github43132@proton.me>
---
 include/bal_errors.h | 33 +++++++++++-------
 src/bal_errors.c     | 82 ++++++++++++++++++++------------------------
 2 files changed, 58 insertions(+), 57 deletions(-)

diff --git a/include/bal_errors.h b/include/bal_errors.h
index dd1ab5c6..e481c2f6 100644
--- a/include/bal_errors.h
+++ b/include/bal_errors.h
@@ -16,41 +16,48 @@ extern "C"
     typedef enum
     {
         // General Errors.
-        //
+
         BAL_SUCCESS                 = 0,
         BAL_ERROR_INVALID_ARGUMENT  = -1,
         BAL_ERROR_ALLOCATION_FAILED = -2,
 
+        // Memory and Translation Errors
+
+        BAL_ERROR_MEMORY_ALIGNMENT = -50,
+        BAL_ERROR_MEMORY_FAULT     = -51,
+
+        /// Engine and Execution Errors
+
+        BAL_ERROR_ENGINE_ALREADY_RUNNING = -100,
+
         /// Guest code tried to execute an unaligned instruction.
-        BAL_ERROR_PC_ALIGNMENT     = -3,
-        BAL_ERROR_MEMORY_ALIGNMENT = -4,
+        BAL_ERROR_PC_ALIGNMENT = -101,
 
         /// Ballistic tried to access memory it was not allowed to access.
-        BAL_ERROR_MEMORY_FAULT        = -5,
-        BAL_ERROR_UNKNOWN_INSTRUCTION = -6,
+        BAL_ERROR_UNKNOWN_INSTRUCTION = -102,
+
+        // Thread Errors
 
         /// Error when creating a thread.
-        BAL_ERROR_THREAD_CREATION = -7,
+        BAL_ERROR_THREAD_CREATION = -150,
 
         /// Error on thread clean up. The user will need to manually clean up the thread's
         /// resources.
-        BAL_ERROR_THREAD_CLEANUP = -8,
-
-        BAL_ERROR_ENGINE_ALREADY_RUNNING = -9,
+        BAL_ERROR_THREAD_CLEANUP = -151,
 
         // IR / Assembler Errors.
 
-        BAL_ERROR_INSTRUCTION_OVERFLOW = -100,
+        BAL_ERROR_INSTRUCTION_OVERFLOW = -200,
 
         /// The decoded register type does not match the expected type.
-        BAL_ERROR_INCORRECT_REGISTER_TYPE = -101,
+        BAL_ERROR_INCORRECT_REGISTER_TYPE = -201,
 
         /// The relative jump or branch offset exceeded the capacity of the target displacement
         /// field.
-        BAL_ERROR_BRANCH_OFFSET_OVERFLOW = -102,
+        BAL_ERROR_BRANCH_OFFSET_OVERFLOW = -202,
 
         /// The provided buffer capacity is too large and would cause an integer overflow.
-        BAL_ERROR_INVALID_CAPACITY = -103,
+        BAL_ERROR_INVALID_CAPACITY = -203,
     } bal_error_t;
 
     /// Converts the enum into a readable string for error handling.
diff --git a/src/bal_errors.c b/src/bal_errors.c
index 219085e7..d78211f4 100644
--- a/src/bal_errors.c
+++ b/src/bal_errors.c
@@ -3,54 +3,48 @@
 const char *
 bal_error_to_string(const bal_error_t error)
 {
-    const char *string = "";
     switch (error)
     {
-        case BAL_ERROR_INVALID_ARGUMENT:
-            string = "function argument is NULL or invalid";
-            break;
-        case BAL_ERROR_ALLOCATION_FAILED:
-            string = "failed to allocate memory";
-            break;
-        case BAL_ERROR_PC_ALIGNMENT:
-            string = "guest code tried to execute an unaligned instruction";
-            break;
-        case BAL_ERROR_MEMORY_ALIGNMENT:
-            string = "buffer is not aligned to the required memory alignment";
-            break;
-        case BAL_ERROR_MEMORY_FAULT:
-            string = "accessed invalid memory";
-            break;
-        case BAL_ERROR_THREAD_CREATION:
-            string = "could not create thread";
-            break;
-        case BAL_ERROR_THREAD_CLEANUP:
-            string = "could not clean up thread";
-            break;
-        case BAL_ERROR_ENGINE_ALREADY_RUNNING:
-            string = "engine already running";
-            break;
-        case BAL_ERROR_UNKNOWN_INSTRUCTION:
-            string = "failed to decode arm instruction";
-            break;
-        case BAL_ERROR_INSTRUCTION_OVERFLOW:
-            string = "instructions array overflowed";
-            break;
-        case BAL_ERROR_INCORRECT_REGISTER_TYPE:
-            string = "incorrect register type";
-            break;
-        case BAL_ERROR_BRANCH_OFFSET_OVERFLOW:
-            string = "relative branch offset exceeds target displacement limit";
-            break;
-        case BAL_ERROR_INVALID_CAPACITY:
-            string = "buffer capacity is too large and would cause integer overflow";
-            break;
         case BAL_SUCCESS:
-            string = "there is no error";
-            break;
-    }
+            return "there is no error";
+        case BAL_ERROR_INVALID_ARGUMENT:
+            return "function argument is NULL or invalid";
+        case BAL_ERROR_ALLOCATION_FAILED:
+            return "failed to allocate memory";
 
-    return string;
+            // --- Memory & Translation ---
+        case BAL_ERROR_MEMORY_ALIGNMENT:
+            return "buffer is not aligned to the required memory alignment";
+        case BAL_ERROR_MEMORY_FAULT:
+            return "accessed invalid or unmapped guest memory";
+
+            // --- Engine & Execution ---
+        case BAL_ERROR_ENGINE_ALREADY_RUNNING:
+            return "engine is already executing guest code";
+        case BAL_ERROR_PC_ALIGNMENT:
+            return "guest code tried to execute an unaligned instruction";
+        case BAL_ERROR_UNKNOWN_INSTRUCTION:
+            return "failed to decode ARM instruction";
+
+            // --- Threading ---
+        case BAL_ERROR_THREAD_CREATION:
+            return "could not create background thread";
+        case BAL_ERROR_THREAD_CLEANUP:
+            return "could not clean up background thread";
+
+            // --- IR / Assembler ---
+        case BAL_ERROR_INSTRUCTION_OVERFLOW:
+            return "instruction buffer or IR arena overflowed";
+        case BAL_ERROR_INCORRECT_REGISTER_TYPE:
+            return "decoded register type mismatch";
+        case BAL_ERROR_BRANCH_OFFSET_OVERFLOW:
+            return "relative branch offset exceeds displacement limit";
+        case BAL_ERROR_INVALID_CAPACITY:
+            return "buffer capacity is too large and would cause integer overflow";
+
+        default:
+            return "unknown error code";
+    }
 }
 
 /*** end of file ***/