feat(hgraph): add support_force_remove switch

[LHT129]

Summary

• add a dedicated support_force_remove HGraph parameter and map it through the public and internal parameter layers
• gate force-remove locking and RemoveMode::FORCE_REMOVE on support_force_remove while keeping support_remove for existing delete-metadata semantics
• update regression tests, examples, and EN/ZH docs to describe the split behavior

Verification

• cmake -S . -B build-release -G Ninja -DCMAKE_BUILD_TYPE=Release -DENABLE_TESTS=ON
• cmake --build build-release --target functests unittests
• ./build-release/tests/unittests "*support_force_remove*"
• ./build-release/tests/functests "HGraph ForceRemove Requires support_force_remove"

Closes: #2085

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Require kind label

Wonderful, this rule succeeded.

• label~=^kind/

🟢 Require version label

Wonderful, this rule succeeded.

• label~=^version/

🟢 Require linked issue for feature/bug PRs

Wonderful, this rule succeeded.

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

[Copilot]

Pull request overview

Adds a dedicated support_force_remove build parameter for HGraph and threads it through constants → external/internal parameter mapping → runtime behavior, so RemoveMode::FORCE_REMOVE and its extra synchronization are explicitly opt-in and no longer conflated with support_remove (delete-tracking metadata).

Changes:

• Introduce/export support_force_remove in public/internal constants and map it into HGraphParameter.
• Gate force-remove locking and RemoveMode::FORCE_REMOVE behind support_force_remove, while keeping support_remove for delete-tracking metadata semantics.
• Update unit/functional tests, examples, and EN/ZH docs to reflect the split behavior.

Reviewed changes

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

Show a summary per file

File	Description
tests/test_hgraph_remove.cpp	Allows building HGraph with/without support_force_remove and adds a regression test for FORCE_REMOVE guard rails.
src/inner_string_params.h	Adds internal string key for support_force_remove and wires it into the default placeholder map.
src/constants.cpp	Exports the new public constant string HGRAPH_SUPPORT_FORCE_REMOVE.
include/vsag/constants.h	Declares the new public constant HGRAPH_SUPPORT_FORCE_REMOVE.
src/algorithm/hgraph_parameter.h	Adds support_force_remove to the HGraph parameter struct.
src/algorithm/hgraph_parameter.cpp	Parses/serializes/compat-checks support_force_remove.
src/algorithm/hgraph_parameter_test.cpp	Extends compatibility and mapping tests for the new parameter.
src/algorithm/hgraph.h	Stores and exposes support_force_remove on the HGraph instance.
src/algorithm/hgraph.cpp	Maps the new external param, gates FORCE_REMOVE & locking, and adjusts add/code-insertion locking behavior.
examples/cpp/303_feature_remove.cpp	Updates example build JSON to use support_force_remove.
docs/hgraph.md	Documents the split between support_remove and support_force_remove and updates examples.
docs/docs/en/src/indexes/hgraph.md	Updates English HGraph parameter docs to describe the split.
docs/docs/zh/src/indexes/hgraph.md	Updates Chinese HGraph parameter docs to describe the split.
docs/docs/en/src/advanced/index_lifecycle.md	Updates lifecycle docs for FORCE_REMOVE gating.
docs/docs/zh/src/advanced/index_lifecycle.md	Updates lifecycle docs for FORCE_REMOVE gating.

Comments suppressed due to low confidence (1)

src/algorithm/hgraph.cpp:1842

• insert_persistent_codes() no longer takes any lock on add_mutex_ (it’s commented out). This function is called from the parallel code-insertion path in Add() (deferred persistent codes) and can also overlap with other concurrent Add() calls, so removing the lock can introduce data races. Given FlattenDataCell is explicitly marked "thread unsafe" (src/datacell/flatten_datacell.h) and InsertVector() isn’t fully synchronized, please restore proper synchronization here (e.g., guard InsertVector calls with add_mutex_, likely an exclusive lock), or otherwise make the underlying code insertion path thread-safe.

HGraph::insert_persistent_codes(const void* data, InnerIdType inner_id) {
    // std::shared_lock add_lock(add_mutex_);
    this->basic_flatten_codes_->InsertVector(data, inner_id);
    if (has_precise_reorder()) {
        this->high_precise_codes_->InsertVector(data, inner_id);
    }

[gemini-code-assist]

Code Review

This pull request introduces a new configuration parameter, support_force_remove, to the HGraph index to explicitly control the availability of the FORCE_REMOVE deletion mode. The changes include updating the index parameter mapping, adding the necessary flag to the HGraph implementation, and updating documentation and tests to reflect this requirement. A potential concurrency issue was identified regarding the commented-out add_mutex_ lock in insert_persistent_codes, which requires further investigation to ensure thread safety.

[LHT129]

@gemini-code-assist The comment about the commented-out add_mutex_ lock in insert_persistent_codes (line 1838) was based on an older commit dcb187a7. In the current commits (97aab97d and later), the lock handling has been properly conditionized:

void HGraph::insert_persistent_codes(const void* data, InnerIdType inner_id) {
    std::shared_lock<std::shared_mutex> add_lock;
    if (not this->support_force_remove()) {
        add_lock = std::shared_lock<std::shared_mutex>(this->add_mutex_);
    }
    // ... insertion code ...
}

When support_force_remove is disabled:

• The read lock on add_mutex_ is taken in insert_persistent_codes, protecting concurrent access.

When support_force_remove is enabled:

• No lock is taken here because add_one_point already holds a write lock on add_mutex_ earlier in the call chain (before insert_codes), which provides exclusive protection for the insertion path.

Regarding the build_by_odescent call: it executes sequentially during the build phase and does not run concurrently with other Add() operations, so the race condition concern does not apply in that path. The lock conditionization is scoped specifically to force-remove workloads.

[gemini-code-assist]

Thank you for the detailed clarification regarding the lock conditionization in insert_persistent_codes. Your explanation regarding the call chain and the sequential nature of build_by_odescent makes the design choice clear and logically sound. The implementation of conditional locking based on support_force_remove appears to correctly handle the synchronization requirements for both modes.

[Copilot]

Pull request overview

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

[wxyucs]

lgtm