doc: update CHUNKS.md with extended layer info

Signed-off-by: Eduardo Silva <[email protected]>

Author: edsiper

CHUNKS.md

@@ -91,6 +91,50 @@ Content Data <       |  |  records  |  |
 Fluent Bit API provides backward compatibility with the previous metadata and content
 format found on series v1.8.
 
+Starting with the Fluent Bit release that introduces direct route persistence, the
+fourth metadata byte now carries feature flags. A zero value preserves the legacy
+layout, while a non-zero value indicates that additional structures follow the tag.
+When the ``FLB_CHUNK_FLAG_DIRECT_ROUTES`` bit is set the tag is terminated with a
+single ``\0`` byte and a routing payload is appended.  Fluent Bit v3.0 and later
+also set the ``FLB_CHUNK_FLAG_DIRECT_ROUTE_LABELS`` bit to store each destination's
+alias (or generated name) alongside its numeric identifier so routes can survive
+configuration changes that renumber outputs.  If any stored identifier exceeds
+65535 the ``FLB_CHUNK_FLAG_DIRECT_ROUTE_WIDE_IDS`` bit is enabled and each ID is
+encoded using four bytes so large configurations remain routable after a restart:
+
+```
+Metadata
+                --   +---------+-------+
+               /     |  0xF1   | 0x77  |  <- Magic Bytes
+              /      +---------+-------+
+             <       |  Type   | Flags |  <- Chunk type and flag bits
+              \      +---------+-------+
+               \     |      Tag        |  <- Tag string (no size prefix)
+                     +---------+-------+
+                     |  0x00   |       |  <- Tag terminator (present when flags != 0)
+                     +---------+-------+
+                     | Routing Length  |  <- uint16_t big endian
+                     +---------+-------+
+                     | Route Count     |  <- uint16_t big endian
+                     +---------+-------+
+                     | Output IDs ...  |  <- Each stored as uint16_t (big endian)
+                     |                 |     or uint32_t when FLB_CHUNK_FLAG_DIRECT_ROUTE_WIDE_IDS
+                     +---------+-------+
+                     | Label Lens ...  |  <- Present when FLB_CHUNK_FLAG_DIRECT_ROUTE_LABELS
+                     +---------+-------+
+                     | Label Bytes ... |  <- Concatenated label strings (no terminators)
+                --   +-----------------+
+```
+
+The routing payload captures the direct route mapping so that filesystem chunks
+loaded by the storage backlog re-use the same outputs after a restart. Chunks
+without direct routes keep the legacy layout (flags byte set to zero) and remain
+fully backwards compatible across Fluent Bit versions. When labels are stored the
+reader first reconstructs routes by matching aliases or numbered names and only
+falls back to numeric identifiers if the textual metadata cannot be matched. This
+ensures that chunks continue to flow to the intended destinations even when the
+output configuration is re-ordered.
+
 ### Fluent Bit <= v1.8
 
 Up to Fluent Bit <= 1.8.x, the metadata and content data is simple, where metadata