core: add request docs for PROTO and PKG before the contract freeze

proto-requests-m1.md: freeze-blockers (error.code wire enum with the full CORE failure taxonomy, TaskSummary.segments meaning, Segment field names) separated from cheap follow-ups (decision event, credential return path, checksum pattern); state-machine ownership split flagged as three-way ADR material. pkg-requests-m1.md: uncomment add_subdirectory(core), pick a test framework, guard VELOX_BUILD_FUZZ on Clang. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01HPPSGhiArbvQgwC2DNiURS
2026-09-09 19:02:53 +04:00
parent e88edd5bd6
commit 910ce4a638
2 changed files with 201 additions and 0 deletions
@@ -0,0 +1,44 @@
+# CORE → PKG/QA — requests
+
+Status: **open**. Raised by lane CORE. PKG/QA owns root build files, `.github/`, and the
+toolchain survey.
+
+## P1. Enable the `core` subdirectory — one line
+
+`CMakeLists.txt` line 38 is the commented `add_subdirectory(core)`. CORE has landed its
+first target (`libveloxcore` + `veloxcore_tests`), so please uncomment it:
+
+```cmake
+add_subdirectory(core)      # lane CORE   → libveloxcore
+```
+
+`core/CMakeLists.txt` is self-contained: it defines the `veloxcore` library and, under
+`if(VELOX_BUILD_TESTS)`, the test target registered with CTest. It pulls in no external
+package yet (stage 1 = `util/` only). `net/` (stage 2) will add `find_package(CURL 8.0)`
+and `meta/` (stage 5) will add `find_package(OpenSSL)` — separate one-line requests when
+those land.
+
+## P2. Test framework decision
+
+No test framework is chosen in the root `CMakeLists.txt` or the docs. CORE is currently
+using a ~90-line header-only harness at `core/tests/support/vtest.hpp` so the lane isn't
+blocked. This is **provisional**. Please pick one (GoogleTest / Catch2 / doctest) and say
+how it's provided (system package vs `FetchContent` vs vendored) — CORE will swap the
+harness for it. The harness API is deliberately tiny (`VT_TEST`, `VT_CHECK`, `VT_REQUIRE`,
+`VT_CHECK_EQ`) so the migration is mechanical.
+
+## P3. `VELOX_BUILD_FUZZ` needs a clang guard
+
+This machine has no `clang++`; libFuzzer is clang-only. `core/CMakeLists.txt` guards the
+fuzz targets behind `if(VELOX_BUILD_FUZZ AND CMAKE_CXX_COMPILER_ID MATCHES "Clang")` so a
+GCC configure with `-DVELOX_BUILD_FUZZ=ON` (the `ci` preset sets it) doesn't hard-fail.
+The `ci` preset in `CMakePresets.json` should either run with clang or expect fuzz targets
+to be skipped on GCC. Flagging so CI doesn't go red on the first CORE push.
+
+## P4. `dev`/`tsan` presets overwrite `CMAKE_CXX_FLAGS`
+
+`CMakePresets.json` sets `CMAKE_CXX_FLAGS` wholesale (`-fsanitize=... -g`), which replaces
+rather than appends. `core/CMakeLists.txt` therefore sets its own `-Wall -Wextra -Werror`
+via `target_compile_options` (not the cache var) so warnings-as-errors survive a
+sanitizer preset. No action needed unless PKG would rather centralize warning flags — just
+noting why CORE sets them at target scope.