Clarify routing-key range and shard-info docs (review notes)

Address the review notes on CollectionShardInfo / RoutingKeyRange:

- RoutingKeyRange: document that an unbounded bound is len==0 (proto3 bytes have
  no presence, so unset and explicitly-empty are indistinguishable on the wire;
  consumers must test len(bound)==0 and the type cannot represent an exactly
  zero-length present bound).
- CollectionShardInfo.last_truncate_time_tick: document its meaning.
- CollectionShardInfo.routing oneof: note that proto cannot enforce agreement
  with routing_mode and the oneof may be unset, so consumers must defend against
  an unset routing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Cai Zhang <cai.zhang@zilliz.com>

Author: xiaocai2333

go-api/schemapb/schema.pb.go

@@ -569,6 +569,8 @@ enum ShardState {
 // Shared definition used by the collection meta, the rootcoord responses and
 // the in-memory routing tables.
 message CollectionShardInfo {
+  // The time tick up to which this shard's WAL has been truncated; 0 when the
+  // shard has never been truncated. Unrelated to routing.
   uint64 last_truncate_time_tick = 1;
   ShardState state = 2;
   // The shard's own vchannel name. Carried explicitly so a consumer can key a
@@ -581,10 +583,14 @@ message CollectionShardInfo {
   // not mistake another concurrent split's targets for its own). Empty unless
   // this shard is an in-progress split target.
   string source_vchannel = 6;
-  // The routing predicate of this shard. The variant matches the collection's
-  // routing_mode. A shard may own more than one piece (e.g. the cold remainder
-  // after a hot tenant in the middle is carved out into its own shard), so each
-  // variant carries a list; the lists of all shards tile the key space exactly.
+  // The routing predicate of this shard. The variant is expected to match the
+  // collection's routing_mode, but proto cannot enforce that agreement, and the
+  // oneof may be unset on the wire (e.g. a legacy/hash-routed shard, which needs
+  // no predicate); consumers must defend against an unset routing and not assume
+  // the variant from routing_mode alone. A shard may own more than one piece
+  // (e.g. the cold remainder after a hot tenant in the middle is carved out into
+  // its own shard), so each variant carries a list; the lists of all shards tile
+  // the key space exactly.
   oneof routing {
     RangeRouting range_routing = 3;
     HashRouting hash_routing = 4;
@@ -598,8 +604,12 @@ message RangeRouting {
   repeated RoutingKeyRange ranges = 1;
 }
 
-// RoutingKeyRange is a half-open routing-key range [lower, upper). A nil bound
-// is unbounded (lower nil = -inf, upper nil = +inf).
+// RoutingKeyRange is a half-open routing-key range [lower, upper). A bound is
+// unbounded when it has length zero: an empty lower is -inf, an empty upper is
+// +inf. proto3 scalar bytes carry no field presence, so an unset bound and an
+// explicitly-empty []byte{} are indistinguishable on the wire and are both
+// treated as unbounded; consumers MUST test len(bound)==0, and the type cannot
+// represent an exactly-empty (zero-length, but present) bound.
 message RoutingKeyRange {
   bytes lower = 1;
   bytes upper = 2;