cloud_storage: add clarifying comments around naming and versions

src/v/cloud_storage/partition_path_utils.h

@@ -17,6 +17,16 @@
 
 namespace cloud_storage {
 
+// Redpanda has supported different formats and naming schemes for partition
+// manifests through its lifetime:
+// - v24.2 and up: cluster-uuid-labeled name, binary format
+// - v23.2 and up: hash-prefixed name, binary format
+// - below v23.2: hash-prefixed name, JSON format
+//
+// Because manifests are persistent state, we must be able to access older
+// versions, in cases we need to read when newer manifests have not yet been
+// written. This header contains methods to build paths for all versions.
+
 // 806a0f4a-e691-4a2b-9352-ec4b769a5e6e/meta/kafka/panda-topic/0_123
 ss::sstring labeled_partition_manifest_prefix(
   const remote_label& cluster_hint,

src/v/cloud_storage/segment_path_utils.h

@@ -16,6 +16,19 @@
 
 namespace cloud_storage {
 
+// Redpanda has supported different naming schemes for segments through its
+// lifetime:
+// - v24.2 and up: cluster-uuid-labeled name
+// - below v24.2: hash-prefixed name
+//
+// Because segments are persistent state, we must be able to access older
+// versions, in cases we need to read when newer manifests have not yet been
+// written. This header contains methods to build paths for all versions.
+//
+// NOTE: the exact segment-name format is still determined by manifest state.
+// As such, this class only guides the prefix, and leaves filename generation
+// to callers (typically via methods in partition_manifest).
+
 // 806a0f4a-e691-4a2b-9352-ec4b769a5e6e/kafka/panda-topic/0_123/0-100-1024-16-v1.log.16
 ss::sstring labeled_segment_path(
   const remote_label& remote_label,

src/v/cloud_storage/topic_path_utils.h

@@ -17,6 +17,16 @@
 
 namespace cloud_storage {
 
+// Redpanda has supported different formats and naming schemes for topic
+// manifests through its lifetime:
+// - v24.2 and up: cluster-uuid-labeled name, binary format
+// - v24.1 and up: hash-prefixed name, binary format
+// - below v24.1: hash-prefixed name, JSON format
+//
+// Because manifests are persistent state, we must be able to access older
+// versions, in cases we need to read when newer manifests have not yet been
+// written. This header contains methods to build paths for all versions.
+
 // meta/kafka/panda-topic
 ss::sstring labeled_topic_manifest_root(const model::topic_namespace& topic);