Planning implementation steps for core modules

.github/workflows/build-clang-fast.yml

@@ -10,15 +10,18 @@ on:
       - develop
       - community
     paths:
-      - 'src/**'
-      - 'include/**'
-      - 'tests/**'
-      - 'cmake/**'
+      - 'src/distributed_tensor/**'
+      - 'include/distributed_tensor/**'
+      - 'tests/epic3_distributed_tensor/**'
       - 'CMakeLists.txt'
       - 'CMakePresets.json'
+      - 'cmake/**/*.cmake'
+      - 'cmake/**/*.txt'
+      - 'cmake/**/*.in'
       - 'vcpkg.json'
       - 'vcpkg-configuration.json'
       - '.github/workflows/build-clang-fast.yml'
+      - '.github/workflows/reusable-cmake-build.yml'
   workflow_dispatch:
 
 permissions:
@@ -39,7 +42,7 @@ jobs:
       submodules: false
       working_directory: .
       setup_command: >-
-        set -euo pipefail; sudo apt-get update -qq; sudo apt-get install -y --no-install-recommends clang lld cmake ninja-build pkg-config librocksdb-dev libgtest-dev libssl-dev zlib1g-dev libzstd-dev libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev libvulkan-dev glslc libboost-system-dev libboost-filesystem-dev libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libpugixml-dev
+        set -euo pipefail; sudo apt-get update -qq; sudo apt-get install -y --no-install-recommends clang lld cmake ninja-build pkg-config librocksdb-dev libgtest-dev libssl-dev zlib1g-dev libzstd-dev libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev libvulkan-dev glslc libcpp-httplib-dev libboost-system-dev libboost-filesystem-dev libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libpugixml-dev
       configure_command: >-
         cmake -S . -B build-clang-fast -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic" -DTHEMIS_BUILD_BENCHMARKS=OFF -DTHEMIS_BUILD_TESTS=ON
       build_command: >-

.github/workflows/build-content-regression.yml

@@ -54,6 +54,7 @@ env:
     libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev
     libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev
     libvulkan-dev glslc
+    libcpphttplib-dev
     libboost-system-dev libboost-filesystem-dev
     libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc
     libpugixml-dev

.github/workflows/build-llm-inference.yml

@@ -149,7 +149,7 @@ jobs:
             build-essential cmake ninja-build pkg-config ccache \
             librocksdb-dev libgtest-dev libssl-dev zlib1g-dev libzstd-dev \
             libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev \
-            libyaml-cpp-dev libcurl4-openssl-dev libboost-system-dev \
+            libyaml-cpp-dev libcurl4-openssl-dev libcpphttplib-dev libboost-system-dev \
             libboost-filesystem-dev libpugixml-dev
 
       - name: Prepare optional submodule paths

.github/workflows/build-mainline.yml

@@ -56,7 +56,7 @@ jobs:
       submodules: false
       working_directory: .
       setup_command: >-
-        set -euo pipefail; echo "CI — Build wrapper delegating to reusable CMake build pipeline"; git config --file .git/config --remove-section submodule.plugins/private/themisdb_ethic_ai || true; git config --file .git/config --remove-section submodule.plugins/private/themisdb_importer || true; git config --file .git/config --remove-section submodule.plugins/private/themisdb_storage || true; git config --file .git/config --remove-section submodule.plugins/private/themisdb_llm_wiki || true; git config --file .git/config --remove-section submodule.plugins/private/themisdb_plugin_signer || true; sudo apt-get update -qq; sudo apt-get install -y --no-install-recommends build-essential cmake ninja-build pkg-config sccache librocksdb-dev libgtest-dev libssl-dev zlib1g-dev libzstd-dev libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev libvulkan-dev glslc libboost-system-dev libboost-filesystem-dev libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libpugixml-dev dpkg-dev rpm; if [ ! -f vcpkg/scripts/buildsystems/vcpkg.cmake ]; then rm -rf vcpkg; git clone --depth 1 https://github.com/microsoft/vcpkg.git vcpkg; fi; test -f vcpkg/scripts/buildsystems/vcpkg.cmake || { echo "::error::vcpkg toolchain missing before bootstrap"; exit 1; }; export VCPKG_ROOT="${GITHUB_WORKSPACE}/vcpkg"; export PATH="${VCPKG_ROOT}:${PATH}"; ./vcpkg/bootstrap-vcpkg.sh -disableMetrics
+        set -euo pipefail; echo "CI — Build wrapper delegating to reusable CMake build pipeline"; git config --file .git/config --remove-section submodule.plugins/private/themisdb_ethic_ai || true; git config --file .git/config --remove-section submodule.plugins/private/themisdb_importer || true; git config --file .git/config --remove-section submodule.plugins/private/themisdb_storage || true; git config --file .git/config --remove-section submodule.plugins/private/themisdb_llm_wiki || true; git config --file .git/config --remove-section submodule.plugins/private/themisdb_plugin_signer || true; sudo apt-get update -qq; sudo apt-get install -y --no-install-recommends build-essential cmake ninja-build pkg-config sccache librocksdb-dev libgtest-dev libssl-dev zlib1g-dev libzstd-dev libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev libvulkan-dev glslc libcpphttplib-dev libboost-system-dev libboost-filesystem-dev libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libpugixml-dev dpkg-dev rpm; if [ ! -f vcpkg/scripts/buildsystems/vcpkg.cmake ]; then rm -rf vcpkg; git clone --depth 1 https://github.com/microsoft/vcpkg.git vcpkg; fi; test -f vcpkg/scripts/buildsystems/vcpkg.cmake || { echo "::error::vcpkg toolchain missing before bootstrap"; exit 1; }; export VCPKG_ROOT="${GITHUB_WORKSPACE}/vcpkg"; export PATH="${VCPKG_ROOT}:${PATH}"; ./vcpkg/bootstrap-vcpkg.sh -disableMetrics
       configure_command: >-
         export VCPKG_ROOT="${GITHUB_WORKSPACE}/vcpkg"; export PATH="${VCPKG_ROOT}:${PATH}"; cmake -S . -B build -DTHEMIS_BUILD_TESTS=ON -DTHEMIS_BUILD_BENCHMARKS=OFF
       build_command: >-

.github/workflows/gate-pr-core.yml

@@ -427,8 +427,7 @@ jobs:
         run: |
           set -euo pipefail
           cmake --preset community-release \
-            -DTHEMIS_BUILD_TESTS=ON \
-            -DTHEMIS_ENABLE_COMPILER_CACHE=OFF 2>&1 | tee /tmp/release-critical-configure.log
+            -DTHEMIS_BUILD_TESTS=ON 2>&1 | tee /tmp/release-critical-configure.log
 
       - name: Build release-critical targets
         run: |

.github/workflows/release-build-matrix.yml

@@ -32,6 +32,7 @@ jobs:
           libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev \
           libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev \
           libvulkan-dev glslc \
+          libcpphttplib-dev \
           libboost-system-dev libboost-filesystem-dev \
           libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libpugixml-dev \
           dpkg-dev rpm
@@ -75,6 +76,7 @@ jobs:
           libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev \
           libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev \
           libvulkan-dev glslc \
+          libcpphttplib-dev \
           libboost-system-dev libboost-filesystem-dev \
           libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libpugixml-dev \
           dpkg-dev rpm

.github/workflows/release-mainline.yml

@@ -710,7 +710,7 @@ jobs:
             build-essential cmake ninja-build pkg-config \
             librocksdb-dev libgtest-dev libssl-dev zlib1g-dev libzstd-dev \
             libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev \
-            libyaml-cpp-dev libcurl4-openssl-dev libboost-system-dev \
+            libyaml-cpp-dev libcurl4-openssl-dev libcpphttplib-dev libboost-system-dev \
             libboost-filesystem-dev libpugixml-dev
 
       - name: Build doku.db

.github/workflows/sanitizer-nightly.yml

@@ -36,7 +36,7 @@ jobs:
       submodules: false
       working_directory: .
       setup_command: >-
-        set -euo pipefail; sudo apt-get update -qq; sudo apt-get install -y --no-install-recommends clang lld cmake ninja-build pkg-config librocksdb-dev libgtest-dev libssl-dev zlib1g-dev libzstd-dev libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev libvulkan-dev glslc libboost-system-dev libboost-filesystem-dev libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libpugixml-dev
+        set -euo pipefail; sudo apt-get update -qq; sudo apt-get install -y --no-install-recommends clang lld cmake ninja-build pkg-config librocksdb-dev libgtest-dev libssl-dev zlib1g-dev libzstd-dev libfmt-dev libspdlog-dev nlohmann-json3-dev libtbb-dev libyaml-cpp-dev libmimalloc-dev libcurl4-openssl-dev libvulkan-dev glslc libcpphttplib-dev libboost-system-dev libboost-filesystem-dev libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc libpugixml-dev
       configure_command: >-
         set -euo pipefail; SAN_MODE="${{ inputs.sanitizer_mode || 'asan-ubsan' }}"; if [ "$SAN_MODE" = "asan-only" ]; then SAN_FLAGS="-fsanitize=address -fno-omit-frame-pointer"; else SAN_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer"; fi; cmake -S . -B build-sanitizer -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_FLAGS="$SAN_FLAGS" -DCMAKE_CXX_FLAGS="$SAN_FLAGS" -DTHEMIS_BUILD_BENCHMARKS=OFF -DTHEMIS_BUILD_TESTS=ON
       build_command: >-

CHANGELOG.md

@@ -9,6 +9,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 (Next release in progress)
 
+### Wave 9 Block 1 — gRPC Core Service Layer (2026-08-26)
+
+- **[W9-1]** `Create` RPC wired: `db_->put(collection:key, data)` with optional `txn_mgr_` session from `transaction_id` field; response includes key + timestamp.
+- **[W9-2]** `Read` RPC wired: `db_->get(collection:key)` with 404 on miss; `ReadResponse.document` fully populated.
+- **[W9-3]** `Update`, `Delete`, `ScanCollection` RPCs wired: Update guards `create_if_missing`; Delete calls `db_->del()`; ScanCollection streams via `db_->scanPrefix(collection + ":")`.
+- **[W9-4]** All Batch RPCs wired (`BatchCreate`, `BatchRead`, `BatchUpdate`, `BatchDelete`); `GetStatus` returns version + uptime + optional stats.
+- **[W9-5]** `BeginTransaction` / `CommitTransaction` / `RollbackTransaction` wired to `TransactionManager::beginTransaction()` / `commitTransaction()` / `rollbackTransaction()` with proto-to-`themis::IsolationLevel` mapping.
+- **[W9-6]** `ExecuteAQL` and `StreamQuery` wired to `aql_engine_->execute(query)`; null-engine path returns gRPC `UNIMPLEMENTED`; `AQLEngine` type alias resolved to `themis::IQueryEngine` in `include/server/themis_core_grpc_service.h`.
+- Timeseries stub: `TODO(W9-5)` comment added in `TimeSeriesApiHandler` constructor pointing to `setAggregatesProvider()` DI injection site.
+- MCP dispatch: `handleToolsCall()` verified fully wired to `tools_` registry map; no code change required.
+- Tests: `tests/server/test_grpc_core_service.cpp` — 16 always-on source/API tests (GCS-01..GCS-16) + 13 full RPC tests under `THEMIS_HAS_CORE_GRPC` guard (GCS-17..GCS-29).
+- Docs: `src/server/ROADMAP.md` W9 Block 1 section added; `src/server/MODULE_GAPS.md` UNIMPLEMENTED grpc items resolved; `src/STUB_INVENTORY.md` entry 58b added and resolved.
+
 ### Documentation
 
 - **2026-08-24 — Documentation Cleanup (DOC-WEEKLY-2026-34):** Archived 1803 AI agent working session files and 18 subdirectories from `ai_working/` to `docs/ARCHIVED/ai-working-history/` via `git mv` (history preserved). Active stream instructions retained in `ai_working/00_START_HERE.md` and `ai_working/00_STREAM_B_START_HERE.md`. Additionally, 35 `docs/` files carrying stale-marker/archive-candidate headers were moved to appropriate `docs/ARCHIVED/` subdirectories (`implementation-summaries/`, `roadmaps/`, `root-drafts/`); duplicate copies already present in the archive were removed.

cmake/CMakeLists.txt

@@ -4420,11 +4420,14 @@ if(CURL_FOUND)
 endif()
 
 # Link cpp-httplib (HTTP server) if available
+find_package(httplib QUIET)
 if(TARGET httplib::httplib)
     target_link_libraries(themis_core PUBLIC httplib::httplib)
     target_compile_definitions(themis_core PUBLIC THEMIS_HAS_HTTPLIB)
+elseif(httplib_FOUND)
+    target_compile_definitions(themis_core PUBLIC THEMIS_HAS_HTTPLIB)
 else()
-    message(STATUS "cpp-httplib target not found - HTTP server adapter may fail to build")
+    message(STATUS "cpp-httplib not found - HTTP server adapter will use stub implementation")
 endif()
 
 # Link MessagePack if available (target names vary by package)
@@ -4518,11 +4521,22 @@ if(THEMIS_ENABLE_GPU)
         target_link_libraries(themis_core PUBLIC gfortran quadmath)
     endif()
     target_compile_definitions(themis_core PUBLIC THEMIS_GPU_ENABLED)
+    # W9-14: Expose THEMIS_HAS_FAISS so advanced_vector_index.cpp enables
+    # the production FAISS code paths (IVF+PQ, HNSW, GPU cloner).
+    target_compile_definitions(themis_core PUBLIC THEMIS_HAS_FAISS)
+    message(STATUS "FAISS found and enabled (THEMIS_HAS_FAISS)")
 elseif(hnswlib_FOUND)
     target_link_libraries(themis_core PUBLIC hnswlib::hnswlib)
     target_compile_definitions(themis_core PUBLIC THEMIS_HNSW_ENABLED)
 endif()
 
+# Expose THEMIS_ROCKSDB_AVAILABLE so sources can guard RocksDB CF usage.
+# RocksDB is always present (build fails above if not found), but we gate
+# behind this flag to allow future conditional builds.
+if(THEMIS_ROCKSDB_TARGET)
+    target_compile_definitions(themis_core PUBLIC THEMIS_ROCKSDB_AVAILABLE)
+endif()
+
 # v1.1.0: Link mimalloc (20-40% memory boost, drop-in replacement)
 if(THEMIS_ENABLE_MIMALLOC AND mimalloc_FOUND)
     # Use DLL version on Windows (mimalloc-static not available in vcpkg binary cache)
@@ -4670,6 +4684,7 @@ endif()
 # gRPC Protocol Support (inter-shard communication - implemented in v1.3.0)
 if(THEMIS_ENABLE_GRPC)
     target_compile_definitions(themis_core PUBLIC THEMIS_ENABLE_GRPC)
+    target_compile_definitions(themis_core PUBLIC THEMIS_HAS_CORE_GRPC)
     message(STATUS "gRPC support enabled (inter-shard communication)")
     find_package(gRPC CONFIG)
     find_package(Protobuf CONFIG)
@@ -5256,6 +5271,10 @@ if(THEMIS_ENABLE_HTTP_SERVER)
     target_compile_definitions(themis_server PRIVATE THEMIS_ENABLE_HTTP_SERVER=1)
 endif()
 
+if(THEMIS_ENABLE_GRPC)
+    target_compile_definitions(themis_server PRIVATE THEMIS_HAS_CORE_GRPC)
+endif()
+
 target_link_libraries(themis_server
     PRIVATE
         themis_core

cmake/ModularBuild.cmake

@@ -2774,6 +2774,21 @@ function(themis_build_modular)
                 target_link_libraries(themis_llm_ext PUBLIC ${THEMIS_ROCKSDB_TARGET})
             endif()
         endif()
+        # cpp-httplib: header-only HTTP server used by grafana_metrics.cpp
+        find_package(httplib QUIET)
+        if(TARGET httplib::httplib)
+            target_link_libraries(themis_llm PUBLIC httplib::httplib)
+            target_compile_definitions(themis_llm PUBLIC THEMIS_HAS_HTTPLIB)
+            if(THEMIS_MODULE_LLM_SPLIT AND TARGET themis_llm_ext)
+                target_link_libraries(themis_llm_ext PUBLIC httplib::httplib)
+                target_compile_definitions(themis_llm_ext PUBLIC THEMIS_HAS_HTTPLIB)
+            endif()
+        elseif(httplib_FOUND)
+            target_compile_definitions(themis_llm PUBLIC THEMIS_HAS_HTTPLIB)
+            if(THEMIS_MODULE_LLM_SPLIT AND TARGET themis_llm_ext)
+                target_compile_definitions(themis_llm_ext PUBLIC THEMIS_HAS_HTTPLIB)
+            endif()
+        endif()
     endif()
 
     if(THEMIS_TRAINING_SOURCES)

include/auth/federated_identity_manager.h

@@ -19,6 +19,7 @@
 
 #include <string>
 #include <vector>
+#include <list>
 #include <unordered_map>
 #include <unordered_set>
 #include <memory>
@@ -178,11 +179,13 @@ class FederatedIdentityManager {
 
     /**
      * @brief Return the normalized issuer URLs of all registered realms.
+     * @return Vector of normalized issuer URLs in their current registry order.
      */
     std::vector<std::string> realmIssuers() const;
 
     /**
      * @brief Return the number of registered realms.
+     * @return Count of realms currently registered in the manager.
      */
     size_t realmCount() const;
 
@@ -325,6 +328,8 @@ class FederatedIdentityManager {
     /**
      * @brief Remove a previously registered cross-provider trust relationship.
      *
+     * @param subject_issuer   Normalized issuer URL of the token source.
+     * @param trusting_issuer  Normalized issuer URL of the realm that trusts it.
      * @return true if the trust was found and removed, false otherwise.
      */
     bool removeCrossProviderTrust(const std::string& subject_issuer,
@@ -359,6 +364,9 @@ class FederatedIdentityManager {
      *
      * Typically used from tests; production code relies on the implicit
      * cache-fill inside validateToken().
+     *
+     * @param token   Raw bearer token used as the cache key.
+     * @param result  Validation result to cache for @p token.
      */
     void cacheValidationResult(const std::string& token,
                                const FederatedValidationResult& result);
@@ -386,6 +394,7 @@ class FederatedIdentityManager {
     /**
      * @brief Return the number of entries currently in the token cache
      *        (including possibly-expired ones not yet evicted).
+     * @return Current number of cached token-validation entries.
      */
     size_t tokenCacheSize() const;
 
@@ -424,9 +433,16 @@ class FederatedIdentityManager {
     // In-memory token validation cache (cross-provider state sync)
     // Protected by cache_mutex_ (separate from mutex_ to avoid lock inversion
     // when validateToken() holds mutex_ and stores to cache).
+    //
+    // [W8-16] Cache keys are SHA-256(token) hex strings (64 chars) rather than
+    // raw JWT strings, preventing unbounded key growth from large bearer tokens.
+    // The LRU order list (cache_lru_order_) enforces kTokenCacheMaxSize cap.
     // -----------------------------------------------------------------------
     mutable std::mutex cache_mutex_;
+    /// @brief Cache map: SHA-256(token) hex → CachedValidation entry.
     std::unordered_map<std::string, CachedValidation> token_cache_;
+    /// @brief LRU order list: front = most recently used key, back = LRU key.
+    std::list<std::string> cache_lru_order_;
 
     // -----------------------------------------------------------------------
     // Cross-provider trust registry: trusting_issuer -> {trusted subject issuers}