[feat](hgraph): restore conjugate-graph enhancement and Pretrain support #2650

Affected area

hgraph

Motivation

The graph-enhancement workflow documented in docs/docs/en/src/advanced/enhance_graph.md:1-55 was implemented only by the deprecated HNSW index. HGraph currently exposes neither Feedback/Pretrain overrides in src/algorithm/hgraph/hgraph.h:69-180 nor conjugate-graph build/search parameters in src/algorithm/hgraph/hgraph_parameter.h:47-119.

Removing HNSW, FreshHNSW, and DiskANN in #2624 therefore leaves no maintained index that can improve hard-query routing through feedback or offline pretraining. HGraph users need an equivalent maintained path without restoring any deprecated index.

Proposed solution

Implement graph enhancement on HGraph using the retained generic groundwork:

• Integrate the reusable ConjugateGraph data structure from src/impl/conjugate_graph.h:30-78 into HGraph build, update, search, serialization, and deserialization paths.
• Add HGraph-scoped build and search parameters for enabling the auxiliary graph and using it during search.
• Override the inner Feedback and Pretrain operations on HGraph and route them through the existing public forwarding in src/index/index_impl.h:400-417.
• Preserve the default unsupported-operation contract for indexes that do not implement the capability.
• Restore an HGraph-based graph-enhancement example and update the active documentation once the runtime support exists.

Focused coverage should include:

• The existing default unsupported checks around src/algorithm/inner_index_interface_test.cpp:205-218.
• Positive HGraph Pretrain and Feedback behavior, including empty, invalid, and redundant inputs.
• Search-result enhancement and the disabled-feature boundary.
• Update-ID behavior and binary/stream serialization round trips.

PR #2624 intentionally retains src/impl/conjugate_graph.cpp and src/index/index_impl.h as implementation groundwork for this follow-up.

Alternatives considered

Restoring HNSW or DiskANN solely to retain this capability would prolong deprecated implementations and is outside the VSAG 1.1 removal direction. Removing the research and feature record would also hide a useful capability instead of migrating it to the maintained graph index.

API / ABI compatibility impact

additive only (no break)

References

• docs/docs/en/src/advanced/enhance_graph.md:1-55
• src/algorithm/hgraph/hgraph.h:69-180
• src/algorithm/hgraph/hgraph_parameter.h:47-119
• src/algorithm/inner_index_interface_test.cpp:205-218
• src/impl/conjugate_graph.h:30-78
• src/index/index_impl.h:400-417
• Related implementation-removal PR: refactor!: remove HNSW and DiskANN; legacy indexes become unsupported #2624

Additional context

This issue is the focused migration follow-up for graph enhancement and Pretrain. It must not reintroduce HNSW, FreshHNSW, or DiskANN functionality.

Related issues

None found.

Drafted with AI assistant: Codex:gpt-5