test(meta): raise meta coverage to >=90% + fix ffi CallbackRegistry crash

[MaxQian888]

Summary

Brings the atom/meta test suite to comprehensive, 1:1-with-headers coverage and fixes two latent bugs in ffi.hpp uncovered along the way.

Tests

• Add the previously-missing tests/meta/reflection/test_refl_field.cpp (covers FieldBase: construction/defaults, member-pointer binding, validators, and the C++23 deducing-this builders incl. derived-type preservation).
• Expand the meta test suites so every header with runtime code reaches ≥90% deduplicated source-line coverage (33 of 34 at 92.5%–100%). Coverage was measured per-test to avoid gcov's per-instantiation line inflation, which otherwise makes template headers report 5–15× their real line count.
• facade_any stops at its reachable ceiling (~88%): the remaining lines are defensive proxy-call catch blocks and the never-invoked less_than_impl, unreachable without fault injection.
• Full suite: 1233 test cases, 0 failures across all 37 meta test executables.

ffi fixes

• CallbackRegistry SIGSEGV: registerCallback stored the raw closure type in std::any while getCallback<Sig> retrieved it as std::function<Sig>; the pointer-form any_cast returned nullptr on the mismatch (it does not throw, so the surrounding catch was dead code) and the null was wrapped in a success result, so callers dereferenced null and crashed. Now the callable is wrapped in a std::function with the deduced signature (sync + async paths), and getCallback null-guards to return TypeMismatch.
• Lazy getHandle: DynamicLibrary::getHandle now honours the load strategy like getFunction (Lazy/Immediate load on access; OnDemand still needs an explicit loadLibrary()).

Note on scope

This branch also carries 6 pre-existing branch-sync / pre-commit.ci bot commits that were already on local dev but not yet on upstream dev; they appear in the diff but are not part of the substantive change above.

🤖 Generated with Claude Code

---

Summary by cubic

Raises atom/meta runtime-header coverage to ≥90% and fixes an ffi callback crash. Adds hot-reloadable components via meta::DynamicLibrary, switches scripting to Python, and adopts atom::type::expected for serialization results.

• New Features

  • Implemented hot reload: Registry::loadComponentFromFile loads modules via meta::DynamicLibrary (opt-in ATOM_COMPONENTS_ENABLE_HOT_RELOAD/hot_reload).
  • Added tests/meta/reflection/test_refl_field.cpp and split shared field logic into atom/meta/refl_field.hpp.
  • Completed the components event system with Event, EventCallback, EventCallbackId in core/types.hpp; enabled events by default; added Registry::registerComponentInstance.

• Refactors and Fixes

  • Scripting: replaced phantom ChaiScript with real Python support and updated language detection.
  • Serialization: APIs now return atom::type::expected (SerializationOutcome/DeserializationOutcome); structured SerializationError added.
  • Type module: moved public symbols into atom::type (e.g., NonCopyable, StaticString, Trackable, PointerSentinel) and updated call sites.
  • Containers: components optionally uses atom::containers fast containers when ATOM_USE_BOOST_CONTAINERS is set.
  • FFI: CallbackRegistry stores std::function<Sig> and returns TypeMismatch on signature mismatch; DynamicLibrary::getHandle respects load strategy.
  • Consolidated “advanced_*” variants: components bindings moved to scripting/bindings; system/command’s advanced executor merged into executor with a new command/command.hpp umbrella.
  • Fixed module macros and re-enabled types/macros tests; demoted hot-path logging to trace/debug; formatted exception messages via fmt::format; removed dead components/data/type_conversion.hpp and the Abseil dependency from package.hpp.
  • Misc: added missing standard headers; aligned event data correctly; updated docs (WARP.md, components/CLAUDE.md) and bumped pre-commit-hooks to v6.0.0.

^{Written for commit f17f583. Summary will update on new commits.}

[sourcery-ai]

Sorry @MaxQian888, your pull request is larger than the review limit of 150000 diff characters

[cubic-dev-ai]

2 issues found across 193 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="atom/meta/constructor.hpp">

<violation number="1" location="atom/meta/constructor.hpp:547">
P2: Missing direct `#include <vector>` for newly introduced `std::vector` usage in `ObjectBuilder`</violation>
</file>

<file name="atom/meta/raw_name.hpp">

<violation number="1" location="atom/meta/raw_name.hpp:137">
P2: GCC member-name parser truncates overloaded operator member names like `operator()` due to forward search for `)` or `}` delimiters. The `find_first_of(")}", start)` call stops at the `)` inside `operator()` itself, returning `operator(` instead of the full name.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic only reviews up to 100 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.
On a pro plan you can use ultrareview for larger PRs.
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Missing direct #include <vector> for newly introduced std::vector usage in ObjectBuilder

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/meta/constructor.hpp, line 547:

<comment>Missing direct `#include <vector>` for newly introduced `std::vector` usage in `ObjectBuilder`</comment>

<file context>
@@ -559,40 +542,45 @@ auto factoryConstructor() {
-    std::function<std::shared_ptr<Class>()> m_buildFunc;
+    // Steps are applied in order at build(); storing them flat avoids the
+    // O(n^2) closure-chain copies of composing a new lambda per step.
+    std::vector<std::function<void(Class&)>> m_steps;
 
 public:
</file context>

[cubic-dev-ai]

P2: GCC member-name parser truncates overloaded operator member names like operator() due to forward search for ) or } delimiters. The find_first_of(")}", start) call stops at the ) inside operator() itself, returning operator( instead of the full name.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/meta/raw_name.hpp, line 137:

<comment>GCC member-name parser truncates overloaded operator member names like `operator()` due to forward search for `)` or `}` delimiters. The `find_first_of(")}", start)` call stops at the `)` inside `operator()` itself, returning `operator(` instead of the full name.</comment>

<file context>
@@ -108,19 +127,22 @@ constexpr std::string_view extract_enum_name(std::string_view name) noexcept {
+    if (auto start = value.rfind("::"); start != std::string_view::npos) {
         start += 2;
-        auto end = name.rfind('}');
+        auto end = value.find_first_of(")}", start);
         if (end == std::string_view::npos) {
-            end = name.size();
</file context>

Suggested change

	auto end = value.find_first_of(")}", start);
	auto end = value.find_last_of(")}");

[cubic-dev-ai]

27 issues found across 127 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="atom/type/robin_hood.hpp">

<violation number="1" location="atom/type/robin_hood.hpp:376">
P1: The write lock added to `insert()` only serializes that single method, leaving every other public access to `table_` unprotected. Both overloads of `find`, `at`, all iterator accessors, `clear`, and `max_load_factor(float)` read or mutate the underlying storage without acquiring `lock_read()` or `lock_write()`. In a concurrent workload, a `find` on one thread can race with an `insert` + `rehash` on another because `rehash` move-assigns `table_` while `find` is still indexing into the old vector. The `reader_lock` and `mutex` threading policies are therefore broken for any pattern beyond single-threaded `insert`-only use. A consistent locking policy should be applied across every public method that touches `table_`, or the policy enum should be removed if thread safety is not intended.</violation>

<violation number="2" location="atom/type/robin_hood.hpp:418">
P0: Default-key lookups can return the wrong element because the new empty-slot-skipping iterator is constructed for a bucket that `find` incorrectly accepts as a match. Empty slots have `dist == 0` and a default-constructed key. Because `find` starts with `dist == 0`, the termination check `table_[idx].dist < dist` is false for an empty ideal bucket, so `find` proceeds to `key_equal_`. If the searched key happens to be the default value, `key_equal_` succeeds and `find` returns an iterator to the empty bucket. The new iterator constructor then calls `skip_empty()`, advancing past the empty slot to the next occupied entry. This means `find(Key{})` can return an iterator to a completely different key, and `at(Key{})` can return the wrong value without throwing. The same issue exists in the const overload.</violation>
</file>

<file name="atom/type/concurrent_map.hpp">

<violation number="1" location="atom/type/concurrent_map.hpp:38">
P2: `ConcurrentMapError` hard-codes `ATOM_FILE_NAME`, `ATOM_FILE_LINE`, and `ATOM_FUNC_NAME` inside its constructor definition, so these macros expand at the class declaration site rather than at each `throw ConcurrentMapError(...)` expression. Every thrown instance therefore records the same fixed file/line/function regardless of which operation failed, defeating the framework exception metadata.

The codebase already has a correct pattern for this in `concurrent_vector.hpp`: a `THROW_CONCURRENT_VECTOR_ERROR` macro passes the macros at the throw site. Consider adding an equivalent `THROW_CONCURRENT_MAP_ERROR(...)` macro and using it at all throw sites instead of `throw ConcurrentMapError(...)`.</violation>

<violation number="2" location="atom/type/concurrent_map.hpp:871">
P0: Calling `adjust_thread_pool_size` from a task running on this pool's own worker thread causes a self-join: `std::thread::join()` throws `std::system_error(resource_deadlock_would_occur)` when invoked on the current thread. The exception leaves `stop_pool = true`, skips the restart block, and permanently disables the executor. Future `submit` calls will all reject with "Thread pool is stopped". Consider rejecting (or deferring) resize requests that originate from a worker thread, or skip `join()` for the calling thread and account for it in the restart logic.</violation>
</file>

<file name="atom/components/data/serialization.cpp">

<violation number="1" location="atom/components/data/serialization.cpp:73">
P2: The `DeserializeFailed` code returned here conflates all JSON deserialization exceptions, including malformed JSON (`nlohmann::json::parse_error`) and type mismatches (`nlohmann::json::type_error`), with genuine component reconstruction failures. The header's own taxonomy defines `InvalidData` for "Input data was malformed or truncated", so JSON parse/type errors should be reported as `InvalidData` so callers can differentiate corrupt input from internal decoding errors. Adding a preceding catch clause for `nlohmann::json::exception` would align the JSON serializer with the documented taxonomy and with the Binary serializer's choice of `InvalidData` for analogous errors.</violation>

<violation number="2" location="atom/components/data/serialization.cpp:334">
P2: Failed serialization and deserialization attempts are no longer counted in the aggregate timing statistics. Previously, `totalSerializationTime` and `totalDeserializationTime` included the elapsed time of every attempt (successful or failed). After the move to `SerializationOutcome`, the error paths return a `SerializationError` with no duration field, and the manager only adds timing inside `outcome.has_value()`. Since `totalSerializations`/`totalDeserializations` are still incremented unconditionally, derived metrics like average time become artificially low and failure-performance analysis is lost.

Consider measuring elapsed time in `SerializationManager` around the serializer call and always adding it to the total, or including a duration field in `SerializationError` so it can be propagated from the serializer on failure.</violation>
</file>

<file name="atom/components/CMakeLists.txt">

<violation number="1" location="atom/components/CMakeLists.txt:78">
P1: The hot-reload `watchComponentChanges` stop path can deadlock. `watchComponentChanges(false)` in `atom/components/core/registry.cpp` acquires a `std::unique_lock` at function scope while the async worker can try to acquire a `shared_lock` on the same mutex between its `while` check and lock acquisition. If the unique lock is held when the worker tries to get a shared lock, the worker blocks forever, and the caller then blocks forever on `fileWatcherFuture_.wait()` without ever releasing the unique lock. Consider unlocking the mutex before waiting on the future: release `unique_lock` before calling `fileWatcherFuture_.wait()`.</violation>
</file>

<file name="atom/type/concurrent_set.hpp">

<violation number="1" location="atom/type/concurrent_set.hpp:38">
P2: The `ConcurrentSetException` hierarchy hard-codes `ATOM_FILE_NAME`, `ATOM_FILE_LINE`, and `ATOM_FUNC_NAME` inside the class constructor definitions. These macros expand at the constructor's source location (inside `concurrent_set.hpp`) rather than at each actual throw site. Consequently, `getFile()`, `getLine()`, and `getFunction()` always return the same fixed location for every operation failure, defeating the framework's diagnostic metadata. Since the PR intent is to integrate with `atom::error::Exception` for framework error handling, the captured location should reflect the failing operation, not the exception class definition.</violation>

<violation number="2" location="atom/type/concurrent_set.hpp:1118">
P1: The `transaction` method snapshots `data` under a shared lock, releases it while running operations, and then restores the stale snapshot on rollback. This silently overwrites any concurrent modifications made by other threads between the snapshot and the rollback, violating the claimed atomicity. The rollback should either use change-based undo, acquire an exclusive lock for the entire operation window (avoiding the recursive-lock deadlock some other way), or the method should document that it does not provide isolation.</violation>
</file>

<file name="example/type/monadic_error_handling_example.cpp">

<violation number="1" location="example/type/monadic_error_handling_example.cpp:4">
P2: The file-level docstring claims this example demonstrates `and_then / map / or_else` chains, but the code never calls `or_else`. An example whose purpose is to document the API should match the operations it says it demonstrates. Either add an `or_else` recovery path to the chain or remove `or_else` from the header description.</violation>

<violation number="2" location="example/type/monadic_error_handling_example.cpp:22">
P2: The `parse` helper silently accepts numeric-prefix input (e.g., `"4oops"` parses as `4`) because `std::stoi` stops at the first non-numeric character when no consumed-length argument is supplied. This contradicts the example's purpose of demonstrating error-handling short-circuits with `expected`. The adjacent `example/type/expected.cpp` already validates the consumed length with `consumed != text.size()`, confirming this is the intended pattern. Pass a `pos` argument to `std::stoi` and return an error when `pos != s.size()`.</violation>
</file>

<file name="atom/type/flatmap.hpp">

<violation number="1" location="atom/type/flatmap.hpp:205">
P0: The newly-reachable large-container lookup path uses `std::lower_bound` on the internal `std::vector`, but the vector is maintained in insertion order (elements are appended by `insert_or_assign` and `operator[]`), not sorted by the comparator. Binary search on an unsorted range produces incorrect results: existing keys can be missed, leading to duplicate insertions and false negatives from `find`/`at`/`contains`. The previous `std::execution::par_unseq` overload prevented this branch from compiling on conforming implementations; removing the execution policy makes the bug reachable. Consider removing this threshold branch so all non-Boost lookups use linear (or SIMD) search, or alternatively ensure the vector stays sorted on insertion if `lower_bound` is intended.</violation>
</file>

<file name="atom/type/no_offset_ptr.hpp">

<violation number="1" location="atom/type/no_offset_ptr.hpp:248">
P1: The `reset` method advertises a strong exception guarantee in its comment, but when `T` is move-constructible with a throwing move constructor, `destroy()` runs before the placement-new move, so if the move throws the old value is already lost and the pointer is left empty. This also regresses behavior for types where direct `T(args...)` would succeed but moving throws: the old code could reset them, the new code cannot.

Consider switching the branch guard from `std::is_move_constructible_v<T>` to `std::is_nothrow_move_constructible_v<T>` so that only types whose move is guaranteed not to throw use the two-phase strategy, and types with a potentially-throwing move fall back to the basic-guarantee in-place path.</violation>
</file>

<file name="example/type/concurrent_vector.cpp">

<violation number="1" location="example/type/concurrent_vector.cpp:17">
P2: The single-argument constructor usage `ConcurrentVector<int> v(2);` is misdocumented as "2 worker threads". Evidence from the old example code shows the two-argument constructor is `(initial_capacity, thread_count)` and the single-argument overload is used as capacity (e.g. `conc_vec(benchmark_size)`). This means `v(2)` creates a capacity-2 vector with the default thread count, not a two-worker pool as the comment claims. Pass both arguments explicitly (e.g. `ConcurrentVector<int> v(0, 2);`) or update the comment to match the actual behavior.</violation>
</file>

<file name="atom/components/CLAUDE.md">

<violation number="1" location="atom/components/CLAUDE.md:149">
P2: The `ATOM_MODULE` example references `MyComponent`, which is never defined in this rewritten document. The preceding examples all use the `Counter` class introduced earlier. This makes the registration snippet inconsistent with the surrounding documentation and uncompilable if copied. Consider using `Counter` here instead, or explicitly defining `MyComponent` if a distinct example type is intended.</violation>
</file>

<file name="atom/type/weak_ptr.hpp">

<violation number="1" location="atom/type/weak_ptr.hpp:655">
P1: `tryLockPeriodic` is documented and named as a fixed-interval retry helper, but it delegates to `tryLockWithRetry`, which performs exponential backoff (multiplying the interval by `2^attempt` after each failure). Callers expecting regular periodic polling will instead get increasingly long delays. Consider either implementing a true fixed-interval loop inside `tryLockPeriodic`, or renaming and re-documenting the method to reflect the exponential-backoff behavior.</violation>

<violation number="2" location="atom/type/weak_ptr.hpp:842">
P2: `batchOperation` switched from the standard library feature-test macro `__cpp_lib_parallel_algorithm` to a project-specific `ATOM_USE_PARALLEL_ALGORITHMS` macro, but that macro is not defined anywhere in the build system or source code. This means builds that previously compiled the `std::for_each(std::execution::par_unseq, ...)` branch whenever the standard library supported parallel algorithms will now silently fall back to sequential processing for large batches. Either restore the feature-test macro (matching `small_vector.hpp` and `bit.hpp`), define `ATOM_USE_PARALLEL_ALGORITHMS` consistently in the build system, or align all headers on the same guard.</violation>
</file>

<file name="atom/components/xmake.lua">

<violation number="1" location="atom/components/xmake.lua:120">
P2: Enabling `hot_reload` defines `ENABLE_HOT_RELOAD=1`, which activates a watcher loop in `atom/components/core/registry.cpp` that calls `std::this_thread::sleep_for`. Neither `registry.cpp` nor `registry.hpp` directly includes `<thread>`; they rely on `<future>` (included conditionally) transitively providing it, which is not portable. Other files in the project that use the same API already include `<thread>` explicitly (e.g., `scripting_api.cpp`). To make the hot-reload build reliable across toolchains, add `#include <thread>` to `registry.cpp` or `registry.hpp`.</violation>
</file>

<file name="atom/type/concurrent_vector.hpp">

<violation number="1" location="atom/type/concurrent_vector.hpp:1021">
P2: Templating `submit_task` to accept move-only callables removed the previous guard against empty `std::function` tasks. When an empty `std::function` is passed, a `packaged_task` is queued and later executed by the worker. `packaged_task::operator()` internally catches the resulting `std::bad_function_call` and stores it in its inaccessible shared state rather than propagating it, so the worker’s own exception-capture logic never fires and the caller never learns of the failure. Consider restoring an emptiness check for `std::function`-like inputs (e.g. with `if constexpr (std::is_same_v<std::decay_t<F>, std::function<void()>>)`) or restricting `submit_task` to internal use if direct public calls with empty callables are not supported.</violation>
</file>

<file name="atom/type/rtype.hpp">

<violation number="1" location="atom/type/rtype.hpp:28">
P1: The new `StringSequence` concept allows deserializing into `std::vector<std::string_view>` because `StringType` includes `std::string_view`. `JsonValue::as_string()` returns a `const std::string&` backed by the JSON parser's internal storage. When that storage is destroyed (e.g., the temporary parsed object goes out of scope), the stored `string_view`s become dangling, leading to use-after-free. Consider narrowing `StringSequence` to exclude non-owning string types such as `std::string_view`.</violation>

<violation number="2" location="atom/type/rtype.hpp:144">
P1: The `from_json` and `from_yaml` deserializers cast untrusted parsed `double` values directly to the reflected member type with `static_cast<MemberType>(it->second.as_number())`. Because `Number<MemberType>` matches all arithmetic types (including unsigned and narrow integrals), this introduces undefined behavior when the parsed value is out of range for the destination type, negative for an unsigned member, NaN, or infinity. The optional validator runs after the cast, so it cannot guard against the UB. Range-checking or clamping the double before casting would make deserialization safe.</violation>
</file>

<file name="atom/type/uint.hpp">

<violation number="1" location="atom/type/uint.hpp:30">
P2: The switch from `throw std::out_of_range(...)` to `THROW_OUT_OF_RANGE(...)` changes the exception type from `std::out_of_range` to `atom::error::OutOfRange`, which does **not** derive from `std::out_of_range`. Callers catching `std::out_of_range` will silently miss the exception. The doc comments (`@throws std::out_of_range`) are now stale too. Either update the documentation to `@throws atom::error::OutOfRange` and note the contract change, or keep the standard exception to preserve backward compatibility.</violation>
</file>

<file name="atom/components/core/registry.cpp">

<violation number="1" location="atom/components/core/registry.cpp:523">
P1: The component name derived from `fs::path(path).stem()` will include the conventional Unix `lib` prefix (e.g., `libfoo` for `libfoo.so`), but the expected exported symbols use the bare module name (e.g., `foo_initialize_registry`). This causes symbol lookups to fail on Linux/macOS for conventionally-named shared libraries.

Consider stripping the `lib` prefix from the stem when it is present, or using a platform-aware extraction so the symbol name matches the module's actual export:</violation>

<violation number="2" location="atom/components/core/registry.cpp:558">
P1: The new library loading code in `loadComponentFromFile` correctly opens a `DynamicLibrary` and stores it in `loadedLibraries_[name]`, but the file-change handler `watchComponentChanges` only calls `reinitializeComponent` when a change is detected. `reinitializeComponent` re-runs the cached initializer and cleanup functions without ever unloading the old shared object or loading the updated binary from disk. As a result, the "hot reload" path executes the old library's code after a file change rather than the new one. To support actual hot reloading, the watcher should reload the shared object (updating `loadedLibraries_[name]`) and re-resolve the entry points before reinitializing the component.</violation>

<violation number="3" location="atom/components/core/registry.cpp:562">
P1: Components loaded from a file won't be watched for hot-reload changes because `loadComponentFromFile` never records the source path in `ComponentInfo::configPath`. The file watcher checks that field and silently skips components when it's empty, so any library loaded here will never trigger a reload. Recording `path` in `info.configPath` inside the post-load critical section fixes the gap.</violation>
</file>

<file name="atom/type/iter.hpp">

<violation number="1" location="atom/type/iter.hpp:531">
P1: `ZipIterator` now risks undefined behavior when the primary (first) range is longer than any non-primary range. `operator++()` increments every iterator unconditionally, and `operator*()` dereferences every iterator unconditionally, yet `operator==()` only checks the first iterator against its end. If a later range exhausts first, the next increment and dereference of that iterator are UB. The previous all-tuple comparison also failed for unequal-length ranges, but it caused an infinite loop rather than a memory-safety issue.

Consider either (a) tracking end iterators so termination can stop at the shortest range, or (b) adding runtime assertions in `operator++`/`operator*` when `ENABLE_DEBUG` is defined so callers detect precondition violations early. At minimum, the class docs should state that the first passed range must be the shortest.</violation>
</file>

<file name="atom/type/optional.hpp">

<violation number="1" location="atom/type/optional.hpp:403">
P1: The rvalue-ref-qualified `value_or` now calls `storage_.reset()` after moving the contained value, which destroys the standard library–compatible semantics of this accessor. `std::optional::value_or` and this class's own `value() &&` / `operator*() &&` all return the moved value without disengaging the optional. After this change, code that calls `std::move(opt).value_or(x)` and later checks `opt.has_value()` will unexpectedly see it empty. Remove the `storage_.reset()` line to restore the previous behavior, or introduce a separate named operation if destructive consumption is intentional.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P0: Default-key lookups can return the wrong element because the new empty-slot-skipping iterator is constructed for a bucket that find incorrectly accepts as a match. Empty slots have dist == 0 and a default-constructed key. Because find starts with dist == 0, the termination check table_[idx].dist < dist is false for an empty ideal bucket, so find proceeds to key_equal_. If the searched key happens to be the default value, key_equal_ succeeds and find returns an iterator to the empty bucket. The new iterator constructor then calls skip_empty(), advancing past the empty slot to the next occupied entry. This means find(Key{}) can return an iterator to a completely different key, and at(Key{}) can return the wrong value without throwing. The same issue exists in the const overload.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/type/robin_hood.hpp, line 418:

<comment>Default-key lookups can return the wrong element because the new empty-slot-skipping iterator is constructed for a bucket that `find` incorrectly accepts as a match. Empty slots have `dist == 0` and a default-constructed key. Because `find` starts with `dist == 0`, the termination check `table_[idx].dist < dist` is false for an empty ideal bucket, so `find` proceeds to `key_equal_`. If the searched key happens to be the default value, `key_equal_` succeeds and `find` returns an iterator to the empty bucket. The new iterator constructor then calls `skip_empty()`, advancing past the empty slot to the next occupied entry. This means `find(Key{})` can return an iterator to a completely different key, and `at(Key{})` can return the wrong value without throwing. The same issue exists in the const overload.</comment>

<file context>
@@ -378,7 +415,7 @@ class unordered_flat_map {
             if (table_[idx].dist == dist &&
                 key_equal_(table_[idx].data.first, key)) {
-                return iterator(table_.begin() + idx);
+                return iterator(table_.begin() + idx, table_.end());
             }
             idx = (idx + 1) & mask;
</file context>

[cubic-dev-ai]

P0: Calling adjust_thread_pool_size from a task running on this pool's own worker thread causes a self-join: std::thread::join() throws std::system_error(resource_deadlock_would_occur) when invoked on the current thread. The exception leaves stop_pool = true, skips the restart block, and permanently disables the executor. Future submit calls will all reject with "Thread pool is stopped". Consider rejecting (or deferring) resize requests that originate from a worker thread, or skip join() for the calling thread and account for it in the restart logic.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/type/concurrent_map.hpp, line 871:

<comment>Calling `adjust_thread_pool_size` from a task running on this pool's own worker thread causes a self-join: `std::thread::join()` throws `std::system_error(resource_deadlock_would_occur)` when invoked on the current thread. The exception leaves `stop_pool = true`, skips the restart block, and permanently disables the executor. Future `submit` calls will all reject with "Thread pool is stopped". Consider rejecting (or deferring) resize requests that originate from a worker thread, or skip `join()` for the calling thread and account for it in the restart logic.</comment>

<file context>
@@ -784,50 +852,40 @@ class concurrent_map {
-                    }
+            }
+            pool_cv.notify_all();
+            for (auto& t : thread_pool) {
+                if (t && t->joinable()) {
+                    t->join();
</file context>

[cubic-dev-ai]

P0: The newly-reachable large-container lookup path uses std::lower_bound on the internal std::vector, but the vector is maintained in insertion order (elements are appended by insert_or_assign and operator[]), not sorted by the comparator. Binary search on an unsorted range produces incorrect results: existing keys can be missed, leading to duplicate insertions and false negatives from find/at/contains. The previous std::execution::par_unseq overload prevented this branch from compiling on conforming implementations; removing the execution policy makes the bug reachable. Consider removing this threshold branch so all non-Boost lookups use linear (or SIMD) search, or alternatively ensure the vector stays sorted on insertion if lower_bound is intended.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/type/flatmap.hpp, line 205:

<comment>The newly-reachable large-container lookup path uses `std::lower_bound` on the internal `std::vector`, but the vector is maintained in insertion order (elements are appended by `insert_or_assign` and `operator[]`), not sorted by the comparator. Binary search on an unsorted range produces incorrect results: existing keys can be missed, leading to duplicate insertions and false negatives from `find`/`at`/`contains`. The previous `std::execution::par_unseq` overload prevented this branch from compiling on conforming implementations; removing the execution policy makes the bug reachable. Consider removing this threshold branch so all non-Boost lookups use linear (or SIMD) search, or alternatively ensure the vector stays sorted on insertion if `lower_bound` is intended.</comment>

<file context>
@@ -199,8 +200,9 @@ class FlatMap {
-                                       data_.end(), key,
+            // NOTE: std::lower_bound has no parallel execution-policy overload
+            // (unlike sort/find); it is already O(log n) binary search.
+            auto it = std::lower_bound(data_.begin(), data_.end(), key,
                                        [this](const auto& pair, const auto& k) {
                                            return comp_(pair.first, k);
</file context>

[cubic-dev-ai]

P1: The write lock added to insert() only serializes that single method, leaving every other public access to table_ unprotected. Both overloads of find, at, all iterator accessors, clear, and max_load_factor(float) read or mutate the underlying storage without acquiring lock_read() or lock_write(). In a concurrent workload, a find on one thread can race with an insert + rehash on another because rehash move-assigns table_ while find is still indexing into the old vector. The reader_lock and mutex threading policies are therefore broken for any pattern beyond single-threaded insert-only use. A consistent locking policy should be applied across every public method that touches table_, or the policy enum should be removed if thread safety is not intended.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/type/robin_hood.hpp, line 376:

<comment>The write lock added to `insert()` only serializes that single method, leaving every other public access to `table_` unprotected. Both overloads of `find`, `at`, all iterator accessors, `clear`, and `max_load_factor(float)` read or mutate the underlying storage without acquiring `lock_read()` or `lock_write()`. In a concurrent workload, a `find` on one thread can race with an `insert` + `rehash` on another because `rehash` move-assigns `table_` while `find` is still indexing into the old vector. The `reader_lock` and `mutex` threading policies are therefore broken for any pattern beyond single-threaded `insert`-only use. A consistent locking policy should be applied across every public method that touches `table_`, or the policy enum should be removed if thread safety is not intended.</comment>

<file context>
@@ -339,6 +370,12 @@ class unordered_flat_map {
+        // Serialize writers per the threading policy. rehash() does not take a
+        // lock itself, so calling it here does not re-enter (the mutex is
+        // non-recursive).
+        lock_write();
+        WriteUnlock guard{this};
+
</file context>

[cubic-dev-ai]

P1: The hot-reload watchComponentChanges stop path can deadlock. watchComponentChanges(false) in atom/components/core/registry.cpp acquires a std::unique_lock at function scope while the async worker can try to acquire a shared_lock on the same mutex between its while check and lock acquisition. If the unique lock is held when the worker tries to get a shared lock, the worker blocks forever, and the caller then blocks forever on fileWatcherFuture_.wait() without ever releasing the unique lock. Consider unlocking the mutex before waiting on the future: release unique_lock before calling fileWatcherFuture_.wait().

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/components/CMakeLists.txt, line 78:

<comment>The hot-reload `watchComponentChanges` stop path can deadlock. `watchComponentChanges(false)` in `atom/components/core/registry.cpp` acquires a `std::unique_lock` at function scope while the async worker can try to acquire a `shared_lock` on the same mutex between its `while` check and lock acquisition. If the unique lock is held when the worker tries to get a shared lock, the worker blocks forever, and the caller then blocks forever on `fileWatcherFuture_.wait()` without ever releasing the unique lock. Consider unlocking the mutex before waiting on the future: release `unique_lock` before calling `fileWatcherFuture_.wait()`.</comment>

<file context>
@@ -73,6 +73,11 @@ option(ATOM_ENABLE_PYTHON "Enable Python scripting support" OFF)
 
+# Hot reload: load components from shared libraries at runtime
+# (Registry::loadComponentFromFile / watchComponentChanges).
+option(ATOM_COMPONENTS_ENABLE_HOT_RELOAD
+       "Enable runtime loading of components from shared libraries" OFF)
+
</file context>

[cubic-dev-ai]

P2: The ATOM_MODULE example references MyComponent, which is never defined in this rewritten document. The preceding examples all use the Counter class introduced earlier. This makes the registration snippet inconsistent with the surrounding documentation and uncompilable if copied. Consider using Counter here instead, or explicitly defining MyComponent if a distinct example type is intended.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/components/CLAUDE.md, line 149:

<comment>The `ATOM_MODULE` example references `MyComponent`, which is never defined in this rewritten document. The preceding examples all use the `Counter` class introduced earlier. This makes the registration snippet inconsistent with the surrounding documentation and uncompilable if copied. Consider using `Counter` here instead, or explicitly defining `MyComponent` if a distinct example type is intended.</comment>

<file context>
@@ -14,611 +14,284 @@
-lifecycle.initializeAll();  // Call onInitialize()
-lifecycle.updateAll(0.016f); // Call onUpdate() with delta time
-lifecycle.shutdownAll();   // Call onShutdown()
+ATOM_MODULE(my_module, [] { return std::make_shared<MyComponent>("my_module"); });
+// exports C entry points: my_module_initialize_registry / _cleanup_registry /
+// _getInstance / _getVersion — used by Registry::loadComponentFromFile.
</file context>

Suggested change

	ATOM_MODULE(my_module, [] { return std::make_shared<MyComponent>("my_module"); });
	ATOM_MODULE(my_module, [] { return std::make_shared<Counter>("my_module"); });

[cubic-dev-ai]

P2: batchOperation switched from the standard library feature-test macro __cpp_lib_parallel_algorithm to a project-specific ATOM_USE_PARALLEL_ALGORITHMS macro, but that macro is not defined anywhere in the build system or source code. This means builds that previously compiled the std::for_each(std::execution::par_unseq, ...) branch whenever the standard library supported parallel algorithms will now silently fall back to sequential processing for large batches. Either restore the feature-test macro (matching small_vector.hpp and bit.hpp), define ATOM_USE_PARALLEL_ALGORITHMS consistently in the build system, or align all headers on the same guard.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/type/weak_ptr.hpp, line 842:

<comment>`batchOperation` switched from the standard library feature-test macro `__cpp_lib_parallel_algorithm` to a project-specific `ATOM_USE_PARALLEL_ALGORITHMS` macro, but that macro is not defined anywhere in the build system or source code. This means builds that previously compiled the `std::for_each(std::execution::par_unseq, ...)` branch whenever the standard library supported parallel algorithms will now silently fall back to sequential processing for large batches. Either restore the feature-test macro (matching `small_vector.hpp` and `bit.hpp`), define `ATOM_USE_PARALLEL_ALGORITHMS` consistently in the build system, or align all headers on the same guard.</comment>

<file context>
@@ -746,12 +834,12 @@ template <typename T>
     size_t successCount = 0;
 
-#ifdef __cpp_lib_parallel_algorithm
+#ifdef ATOM_USE_PARALLEL_ALGORITHMS
     if (parallelThreshold > 0 && weakPtrs.size() >= parallelThreshold) {
         std::atomic<size_t> atomicCount{0};
</file context>

Suggested change

	#ifdef ATOM_USE_PARALLEL_ALGORITHMS
	#ifdef __cpp_lib_parallel_algorithm

[cubic-dev-ai]

P2: Enabling hot_reload defines ENABLE_HOT_RELOAD=1, which activates a watcher loop in atom/components/core/registry.cpp that calls std::this_thread::sleep_for. Neither registry.cpp nor registry.hpp directly includes <thread>; they rely on <future> (included conditionally) transitively providing it, which is not portable. Other files in the project that use the same API already include <thread> explicitly (e.g., scripting_api.cpp). To make the hot-reload build reliable across toolchains, add #include <thread> to registry.cpp or registry.hpp.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/components/xmake.lua, line 120:

<comment>Enabling `hot_reload` defines `ENABLE_HOT_RELOAD=1`, which activates a watcher loop in `atom/components/core/registry.cpp` that calls `std::this_thread::sleep_for`. Neither `registry.cpp` nor `registry.hpp` directly includes `<thread>`; they rely on `<future>` (included conditionally) transitively providing it, which is not portable. Other files in the project that use the same API already include `<thread>` explicitly (e.g., `scripting_api.cpp`). To make the hot-reload build reliable across toolchains, add `#include <thread>` to `registry.cpp` or `registry.hpp`.</comment>

<file context>
@@ -111,6 +117,10 @@ target("atom-component")
         add_defines("ATOM_ENABLE_PYTHON=1")
     end
 
+    if has_config("hot_reload") then
+        add_defines("ENABLE_HOT_RELOAD=1")
+    end
</file context>

[cubic-dev-ai]

P2: Templating submit_task to accept move-only callables removed the previous guard against empty std::function tasks. When an empty std::function is passed, a packaged_task is queued and later executed by the worker. packaged_task::operator() internally catches the resulting std::bad_function_call and stores it in its inaccessible shared state rather than propagating it, so the worker’s own exception-capture logic never fires and the caller never learns of the failure. Consider restoring an emptiness check for std::function-like inputs (e.g. with if constexpr (std::is_same_v<std::decay_t<F>, std::function<void()>>)) or restricting submit_task to internal use if direct public calls with empty callables are not supported.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/type/concurrent_vector.hpp, line 1021:

<comment>Templating `submit_task` to accept move-only callables removed the previous guard against empty `std::function` tasks. When an empty `std::function` is passed, a `packaged_task` is queued and later executed by the worker. `packaged_task::operator()` internally catches the resulting `std::bad_function_call` and stores it in its inaccessible shared state rather than propagating it, so the worker’s own exception-capture logic never fires and the caller never learns of the failure. Consider restoring an emptiness check for `std::function`-like inputs (e.g. with `if constexpr (std::is_same_v<std::decay_t<F>, std::function<void()>>)`) or restricting `submit_task` to internal use if direct public calls with empty callables are not supported.</comment>

<file context>
@@ -983,12 +1014,12 @@ class concurrent_vector {
+    // std::promise). A std::function parameter would reject them since
+    // std::function requires its target to be copy-constructible.
+    template <typename F>
+    void submit_task(F&& task) {
+        std::packaged_task<void()> packaged(std::forward<F>(task));
         {
</file context>

[cubic-dev-ai]

P2: The switch from throw std::out_of_range(...) to THROW_OUT_OF_RANGE(...) changes the exception type from std::out_of_range to atom::error::OutOfRange, which does not derive from std::out_of_range. Callers catching std::out_of_range will silently miss the exception. The doc comments (@throws std::out_of_range) are now stale too. Either update the documentation to @throws atom::error::OutOfRange and note the contract change, or keep the standard exception to preserve backward compatibility.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At atom/type/uint.hpp, line 30:

<comment>The switch from `throw std::out_of_range(...)` to `THROW_OUT_OF_RANGE(...)` changes the exception type from `std::out_of_range` to `atom::error::OutOfRange`, which does **not** derive from `std::out_of_range`. Callers catching `std::out_of_range` will silently miss the exception. The doc comments (`@throws std::out_of_range`) are now stale too. Either update the documentation to `@throws atom::error::OutOfRange` and note the contract change, or keep the standard exception to preserve backward compatibility.</comment>

<file context>
@@ -24,7 +27,7 @@ constexpr uint32_t MAX_UINT32 = 0xFFFFFFFF;
 constexpr auto operator""_u8(unsigned long long value) -> uint8_t {
     if (value > MAX_UINT8) {  // uint8_t maximum value is 0xFF
-        throw std::out_of_range("Value exceeds uint8_t range");
+        THROW_OUT_OF_RANGE("Value exceeds uint8_t range");
     }
     return static_cast<uint8_t>(value);
</file context>