fix(store): allocate graph id before batch writes

[contrueCT]

Overview

Important

HStore uses a 2-byte GraphId as the graph-isolation boundary. Before this fix, a new graph whose first write used batch PUT or MERGE could encode data with the reserved missing GraphId 0xFFFE. Multiple graphs could then share the same physical RocksDB key range.

Closes #3095. This PR extracts the focused fix from hugegraph#163.

Physical key layout

┌──────────────────┬──────────────────────┬──────────────────┐
│ GraphId · 2 bytes │ Logical key          │ Key code · 2 bytes │
└──────────────────┴──────────────────────┴──────────────────┘

The GraphId prefix is what keeps data from different graphs in separate physical ranges:

Graph	Expected physical key	Buggy first batch write
Graph A	0001 │ shared-key │ code	FFFE │ shared-key │ code
Graph B	0002 │ shared-key │ code	FFFE │ shared-key │ code

65534 (0xFFFE) is reserved for a missing GraphId mapping. The old batch path called getKey(), which returned this sentinel instead of allocating an ID.

Trigger conditions

The collision requires all three conditions:

1. New graph	2. No mapping	3. First write is batched
The graph has not written data in this partition	No GraphId exists for the graph in the target partition	The first operation enters batch PUT or MERGE

Once multiple graphs meet these conditions in the same partition, they share the FFFE prefix.

Data impact

Operation	Result when prefixes collide
PUT	The same logical key can overwrite another graph's value
MERGE	Counters from different graphs can be combined
TRUNCATE	Deleting the shared physical range can remove another graph's data

Note

RocksDB accepts these keys as valid, so the corruption is silent: requests can succeed without exceptions, failed health checks, or Raft errors.

Why this can remain hidden in a long-running deployment

• Normal single-write paths allocate a GraphId before encoding the key.
• Long-running graphs usually already have a persisted mapping and never re-enter the first-write state.
• The failure needs multiple new graphs in the same partition; PUT/MERGE collisions are most visible when their logical keys overlap.
• Graph truncate is uncommon, and the storage layer cannot distinguish an unintended shared prefix from a valid key range.

Fix

Before	After
Batch PUT/MERGE used getKey()	Batch PUT/MERGE uses getKeyOrCreate()
Missing mapping encoded as FFFE	A real GraphId is allocated before key encoding
Truncate could race with in-flight encoded keys	A graph/partition lifecycle lock fences transaction commit or rollback from truncate
Batch failures could retain transaction resources	All three batch call sites roll back and release the session and lifecycle lock

The first-allocation path also checks whether the vertex table exists before scanning it. This avoids upgrading the column-family read lock held by the prepared batch into a write path that creates the missing table.

Regression coverage

BatchGraphIsolationTest exercises the real BusinessHandler.doBatch() and RocksDB path:

• distinct PUT values for the same logical key in two graphs;
• target-graph deletion and neighboring-graph preservation after truncate;
• isolated MERGE counters;
• first batch write on an empty partition without creating the vertex table;
• rollback of failed transfer batches;
• truncate waiting for an in-flight batch transaction.

mvn test -pl hugegraph-store/hg-store-test -am \
    -P store-core-test -Djacoco.skip=true -ntp

Scope

This focused change keeps the physical-key format, public APIs, dependencies, configuration, and CI workflow unchanged. It does not repair already affected data or include broader GraphId lifecycle, ID-reuse, or historical-data migration work.

PR checklist

• Regression coverage added and verified
• No dependency or configuration changes
• No public API changes
• Documentation update not required

[imbajin]

Blocking: yes. Summary: The new batch graph-ID path can leave RocksDB transaction locks held on allocation errors, persist IDs for batches that never commit, and reuse an ID while an in-flight batch still owns encoded keys. The added regression test also exercises an invalid partition instead of the empty-table transaction path. Evidence: exact-head static review; mvn test -pl hugegraph-store/hg-store-test -am -P store-core-test -Djacoco.skip=true -ntp passed 3 tests locally; latest-head CI completed, with Codecov upload 429 treated as non-blocking.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 82 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.41%. Comparing base (c9a646d) to head (a0c34a7).
⚠️ Report is 5 commits behind head on master.

Files with missing lines	Patch %	Lines
.../hugegraph/store/business/BusinessHandlerImpl.java	0.00%	47 Missing ⚠️
...ache/hugegraph/store/business/DataManagerImpl.java	0.00%	12 Missing ⚠️
...che/hugegraph/store/business/DefaultDataMover.java	0.00%	12 Missing ⚠️
...ache/hugegraph/store/business/BusinessHandler.java	0.00%	6 Missing ⚠️
...rg/apache/hugegraph/store/meta/GraphIdManager.java	0.00%	5 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3153      +/-   ##
============================================
- Coverage     39.23%   37.41%   -1.82%     
- Complexity      264     6447    +6183     
============================================
  Files           771      800      +29     
  Lines         65938    68653    +2715     
  Branches       8759     9106     +347     
============================================
- Hits          25872    25688     -184     
- Misses        37310    39951    +2641     
- Partials       2756     3014     +258     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[imbajin]

TODO: check the diff carefully (inconsistent)