[imbajin]

Purpose of the PR

A valid 2,500-edge batch update can exceed the off-heap binary key limit and fail before reaching the backend. Oversized query keys now bypass that cache; ordinary short query keys avoid an additional UTF-8 encoding and byte-array allocation in the guard.

Main Changes

• Keep non-query IDs on the existing path. Read the query string length once: values at or below ID_LEN_MAX / 3 pass immediately, values above ID_LEN_MAX bypass off-heap caching, and only the middle interval needs a UTF-8 byte-length check.
• Derive the safe bound from the existing limit. UTF-8 needs at most three bytes per UTF-16 code unit, including surrogate pairs, so the shortcut preserves the allowed key range.
• Apply the shared guard to off-heap lookup, insertion and removal. Keep RAM caching, backend fallback, batch limits and persistent ID encoding unchanged; add no byte cache or lock.

Verifying these changes

The old guard fails the new zero-extra-encoding regression for short keys. Boundary checks cover ASCII, Chinese text and surrogate pairs, including the exact UTF-8 limit and overflow. Real LevelCache regressions cover RAM and off-heap hits, invalidation, misses and backend refetch. Java 17 formatting, clean compilation, the cache test groups and three independent final reviews passed. New-head CI is pending.

The earlier patched service completed two 2,500-edge SUM updates with typed-value and endpoint readback, and rejected a 2,501-edge request without writes. Those receipts belong to the earlier source; this performance supplement does not claim a new live-service run, runtime cache-hit metric, restart or complete C04 acceptance.

Documentation Status

Doc - No Need: internal cache guard optimization; no API, configuration or persistent format change.

Implementation illustration

Oversized query keys bypass the off-heap tier so cache misses can reach the backend; short keys avoid UTF-8 encoding in the guard. RAM caching and persistent ID encoding remain unchanged. Source-level behavior illustration, not a runtime or CI result.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.62%. Comparing base (68fb045) to head (4d92853).

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3321      +/-   ##
============================================
- Coverage     52.63%   52.62%   -0.01%     
  Complexity     2435     2435              
============================================
  Files           770      770              
  Lines         67694    67707      +13     
  Branches       9172     9175       +3     
============================================
+ Hits          35631    35632       +1     
- Misses        28520    28533      +13     
+ Partials       3543     3542       -1     

☔ 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.

[bitflicker64]

Blocking: no. Summary: The guard keeps query keys whose UTF-8 form exceeds BytesBuffer.ID_LEN_MAX out of the off-heap tier on lookup, insert, containsKey and remove, so a large edge batch query misses the cache and reaches the backend instead of failing in BytesBuffer.writeId; other Id types and keys within the limit behave as before. Evidence: read the full diff at 4d92853 with OffheapCache, LevelCache, AbstractCache, CachedBackendStore.QueryId, QueryIdOffHeap, CachedGraphTransaction.fetchEdgeBatch and BytesBuffer.writeId; the two length shortcuts are sound because UTF-8 uses between one and three bytes per UTF-16 code unit; mvn test -pl hugegraph-server/hugegraph-test -am -P unit-test -Dtest='CacheTest*' on JDK 17 ran 88 tests with 0 failures (OffheapCacheTest 31, RamCacheTest 25, LevelCacheTest 32); Server CI, Compatibility CI and CodeQL are green on this head, and only the informational codecov/project status is red (-0.01%).