diff --git a/CMakeLists.txt b/CMakeLists.txt
index 70e8d6d..24d544e 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -20,22 +20,12 @@ add_definitions(${PROJECT_CXX_FLAGS})
 # ----------------------------------------------------------------
 # output targets
 
+add_subdirectory(src/arena)
 #add_subdirectory(utest)
 
 # ----------------------------------------------------------------
-# header-only library
+# cmake export
 
-set(SELF_LIB xo_arena)
-xo_add_headeronly_library(${SELF_LIB})
-xo_install_library4(${SELF_LIB} ${PROJECT_NAME}Targets)
 xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
 
-# ----------------------------------------------------------------
-# input dependencies
-#
-# NOTE: dependency set here must be kept consistent with
-#       xo-arena/cmake/xo_arenaConfig.cmake.in
-
-#xo_headeronly_dependency(${SELF_LIB} xo_flatstring)
-
 # end CMakeLists.txt
diff --git a/README.md b/README.md
deleted file mode 100644
index 6c14c75..0000000
--- a/README.md
+++ /dev/null
@@ -1 +0,0 @@
-# xo-arena
diff --git a/cmake/xo_arenaConfig.cmake.in b/cmake/xo_arenaConfig.cmake.in
index b5c3cd5..3b32fb0 100644
--- a/cmake/xo_arenaConfig.cmake.in
+++ b/cmake/xo_arenaConfig.cmake.in
@@ -6,7 +6,7 @@ include(CMakeFindDependencyMacro)
 #       must coordinate with xo_dependency() calls
 #       in CMakeLists.txt
 #
-#find_dependency(xo_flatstring)
+find_dependency(xo_reflectutil)
 
 include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Targets.cmake")
 check_required_components("@PROJECT_NAME@")
diff --git a/include/xo/arena/AllocError.hpp b/include/xo/arena/AllocError.hpp
new file mode 100644
index 0000000..ca98b36
--- /dev/null
+++ b/include/xo/arena/AllocError.hpp
@@ -0,0 +1,79 @@
+/** @file AllocError.hpp
+ *
+ *  @author Roland Conybeare, Dec 2025
+ **/
+
+#pragma once
+
+#include <cstdint>
+#include <cstddef>
+
+namespace xo {
+    namespace mm {
+        enum class error : int32_t {
+            /** sentinel **/
+            invalid = -1,
+            /** not an error **/
+            ok,
+            /** reserved size exhauged **/
+            reserve_exhausted,
+            /** unable to commit (i.e. mprotect failure) **/
+            commit_failed,
+            /** allocation size too big (See @ref ArenaConfig::header_size_mask_) **/
+            header_size_mask,
+            /** sub_alloc not preceded by super alloc (or another sub_alloc) **/
+            orphan_sub_alloc,
+            /** attempt to call alloc_info for allocator with alloc header feature disabled
+             *  (e.g. @ref see ArenaConfig::store_header_flag_)
+             **/
+            alloc_info_disabled,
+            /** attempt to call alloc_info for address not owned by allocator **/
+            alloc_info_address,
+            /** for example: alloc iteration not supported in arenas with
+             *  AllocConfig.store_header_flag_ = false
+             **/
+            alloc_iterator_not_supported,
+            /** attempt to deref an iterator that does not refer to an alloc **/
+            alloc_iterator_deref,
+            /** attempt to advance an iterator that does not refer to an alloc **/
+            alloc_iterator_next,
+        };
+
+        struct AllocError {
+            using size_type = std::size_t;
+            using value_type = std::byte*;
+
+            AllocError() = default;
+            explicit AllocError(error err,
+                                    uint32_t seq) : error_{err},
+                                                    error_seq_{seq} {}
+            AllocError(error err,
+                           uint32_t seq,
+                           size_type req_z,
+                           size_type com_z,
+                           size_type rsv_z) : error_{err},
+                                              error_seq_{seq},
+                                              request_z_{req_z},
+                                              committed_z_{com_z},
+                                              reserved_z_{rsv_z} {}
+
+            static const char * error_description(error x);
+
+            /** error code **/
+            error error_ = error::ok;
+
+            /** sequence# of this error.
+             *  Each error event within an allocator gets next sequence number
+             **/
+            uint32_t error_seq_ = 0;
+            /** reqeust size assoc'd with errror **/
+            size_type request_z_ = 0;
+            /** committed allocator memory at time of error **/
+            size_type committed_z_ = 0;
+            /** reserved allocator memory at time of error **/
+            size_type reserved_z_ = 0;
+        };
+    } /*namespace mm*/
+} /*namespace xo*/
+
+/* end AllocError.hpp */
diff --git a/src/arena/AllocError.cpp b/src/arena/AllocError.cpp
new file mode 100644
index 0000000..43c1678
--- /dev/null
+++ b/src/arena/AllocError.cpp
@@ -0,0 +1,45 @@
+/** @file AllocError.cpp
+ *
+ *  @author Roland Conybeare, Dec 2025
+ **/
+
+#include "AllocError.hpp"
+
+namespace xo {
+    namespace mm {
+
+        const char *
+        AllocError::error_description(error x)
+        {
+            switch (x) {
+            case error::invalid:
+                break;
+            case error::ok:
+                return "ok";
+            case error::reserve_exhausted:
+                return "reserve-exhausted";
+            case error::commit_failed:
+                return "commit-failed";
+            case error::header_size_mask:
+                return "header-size-mask";
+            case error::orphan_sub_alloc:
+                return "orphan-sub-alloc";
+            case error::alloc_info_disabled:
+                return "alloc-info-disabled";
+            case error::alloc_info_address:
+                return "alloc-info-address";
+            case error::alloc_iterator_not_supported:
+                return "alloc-iterator-not-supported";
+            case error::alloc_iterator_deref:
+                return "alloc-iterator-deref";
+            case error::alloc_iterator_next:
+                return "alloc-iterator-next";
+            }
+
+            return "?error";
+        }
+
+    } /*namespace mm*/
+} /*namespace xo*/
+
+/* end AllocError.cpp */
diff --git a/src/arena/CMakeLists.txt b/src/arena/CMakeLists.txt
new file mode 100644
index 0000000..bc969b7
--- /dev/null
+++ b/src/arena/CMakeLists.txt
@@ -0,0 +1,19 @@
+# xo-arena/src/CMakeLists.txt
+
+set(SELF_LIB xo_arena)
+set(SELF_SRCS
+    AllocError.cpp
+)
+
+xo_add_shared_library4(${SELF_LIB} ${PROJECT_NAME}Targets ${PROJECT_VERSION} 1 ${SELF_SRCS})
+xo_install_include_tree3(include/xo/arena)
+
+# ----------------------------------------------------------------
+# input dependencies
+#
+# NOTE: dependency set here must be kept consistent with
+#       xo-arena/cmake/xo_arenaConfig.cmake.in
+
+xo_dependency(${SELF_LIB} xo_reflectutil)
+
+# end src/CMakeLists.txt