fix(hgraph): drain parallel build futures on worker errors

[jac0626]

Change Type

• Bug fix
• New feature
• Improvement/Refactor
• Documentation
• CI/Build/Infra

Linked Issue

• Fixes: [bug](hgraph): drain parallel build worker exceptions before returning #2352

What Changed

• Add a shared HGraph helper that waits all submitted std::future<void> tasks before rethrowing the first worker exception.
• Use the helper in HGraph parallel Add() and deferred persistent-code insertion, so Build() cannot return while already-submitted workers are still touching the index.
• Reuse the helper in the build-cache refine path, replacing its local duplicate drain logic.
• Add a regression test using an unsupported RaBitQ build-by-base configuration with build_thread_count > 1; the expected behavior is a clean INTERNAL_ERROR without a segfault.

Test Evidence

• make fmt
• make lint
• make test
• make cov, run tests, and collect coverage
• Other (describe below)

Test details:

# Red before the fix
./build/tests/functests "HGraph parallel build drains worker exceptions"
Segmentation fault
EXIT_STATUS=139

# Green after the fix
./build/tests/functests "HGraph parallel build drains worker exceptions"
All tests passed (4 assertions in 1 test case)
EXIT_STATUS=0

# Formatting/whitespace
clang-format-15 -i src/algorithm/hgraph/hgraph_build.cpp tests/test_hgraph.cpp
git diff --check

# Existing RaBitQ no-reorder smoke check on main
/tmp/vsag_hgraph_rabitq_main_repro
Build ok, count=1000
Search ok, returned=10
EXIT_STATUS=0

Compatibility Impact

• API/ABI compatibility: none.
• Behavior changes: unsupported HGraph build configurations still return the original error, but parallel builds now wait all submitted workers before returning that error.

Performance and Concurrency Impact

• Performance impact: none expected on success paths; the helper still waits the same futures.
• Concurrency/thread-safety impact: improved error-path safety by preventing worker tasks from outliving the failed build call.

Documentation Impact

• No docs update needed
• Updated docs:
  • README.md
  • DEVELOPMENT.md
  • CONTRIBUTING.md
  • Other:

Risk and Rollback

• Risk level: low.
• Rollback plan: revert this commit to restore the previous future waiting behavior.

Checklist

• I have linked the relevant issue (required for kind/bug and kind/feature; see "Linked Issue" above)
• I have added/updated tests for new behavior or bug fixes
• I have considered API compatibility impact
• I have updated docs if behavior/workflow changed
• My commit messages follow project conventions (Conventional Commits, optional [skip ci] prefix)

[mergify]

Merge Protections

🟢 All 3 merge protections satisfied — ready to merge.

Show 3 satisfied protections

🟢 Require kind label

• label~=^kind/

🟢 Require version label

• label~=^version/

🟢 Require linked issue for feature/bug PRs

• body~=(?im)(?:^|[\s\-\*])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s+(?:#\d+|[\w.\-]+/[\w.\-]+#\d+|https?://github\.com/[\w.\-]+/[\w.\-]+/issues/\d+)

[gemini-code-assist]

Code Review

This pull request introduces a helper function wait_all_futures to consolidate the logic for waiting on parallel worker threads and safely propagating exceptions. It replaces several manual future-waiting loops with this helper and adds a unit test to verify exception handling during parallel builds. The reviewer suggests checking future.valid() before calling future.get() in the helper function to avoid potential std::future_error exceptions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.

Fixes a concurrency-related crash in HGraph parallel builds by ensuring all submitted worker futures are drained before surfacing worker exceptions, preventing background tasks from outliving a failed Build() call.

Changes:

• Introduce a shared helper to wait/drain a vector of std::future<void> while capturing and rethrowing the first observed exception.
• Use the helper across parallel Add() paths and the build-cache refine path to avoid early returns with still-running workers.
• Add a regression test for an unsupported RaBitQ build-by-base parallel configuration to ensure failure is a clean INTERNAL_ERROR (no segfault).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
tests/test_hgraph.cpp	Adds a regression test that reproduces the prior segfault and asserts clean error behavior in parallel build mode.
src/algorithm/hgraph/hgraph_build.cpp	Adds and adopts a shared future-drain helper to make error paths safe in parallel build workflows.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.