[dual-timeline 1/N] Add secondary timeline metadata, root offset ring, and lifecycle management

Introduce the foundational infrastructure for dual-timeline support:

Types (category/mpt/detail/timeline.hpp):
- timeline_id enum (primary/secondary) and NUM_TIMELINES constant
- timeline_compaction_state struct with per-timeline compaction boundary

Metadata (category/mpt/detail/db_metadata.hpp):
- secondary_timeline_header_t carved from future_variables_unused:
  version_lower_bound_, next_version_, active_ flag
- Total db_metadata size unchanged (528512 bytes) for backward compat

UpdateAux (trie.hpp, trie.cpp, update_aux.cpp):
- Per-timeline compaction state array (timeline_[NUM_TIMELINES]) with
  tl(timeline_id) accessor, replacing bare member fields
- Secondary root offset ring mapped from cnv chunk 0's unused space
  (65536 entries, 512KB per copy)
- root_offsets_delegator parameterized on timeline_id
- timeline_active(), get_root_offset_at_version(v, tid),
  db_history_{min,max}_version(tid), version_is_valid_ondisk(v, tid)
- Lifecycle: activate_secondary_timeline (initializes compaction from
  primary), deactivate_secondary_timeline, promote_secondary_to_primary

Tests:
- db_metadata_test: layout, field offsets, zero-init semantics,
  read/write round-trip, memcpy survival, no overlap with consensus
- timeline_test: enum values, default construction, trivial copyability
- update_aux_test: secondary ring mapping, activate/deactivate lifecycle,
  ring push/read, promote, per-timeline version queries,
  version_is_valid_ondisk per-timeline

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: maxkozlovsky

category/mpt/db_metadata_context.cpp

@@ -105,7 +105,50 @@ DbMetadataContext::DbMetadataContext(AsyncIO &io)
         }
     }
 
-    // Version mismatch detection
+    // Migration: MONAD007 -> MONAD008. Old code left future_variables_unused
+    // filled with 0xff; under the new layout those bytes overlap the newly
+    // introduced secondary_timeline header and would spuriously mark it
+    // active_=1. Zero the header and bump the magic. Each copy is migrated
+    // independently: if a crash strands one copy at MONAD007, on restart the
+    // magic-validation step above restores from the MONAD008 copy when that
+    // side is valid, otherwise the per-copy migration loop below picks up
+    // whichever copies still carry MONAD007. Either path converges to both
+    // copies at MONAD008.
+    auto const is_previous_magic = [](detail::db_metadata const *m) {
+        return 0 == memcmp(
+                        m->magic,
+                        detail::db_metadata::PREVIOUS_MAGIC,
+                        detail::db_metadata::MAGIC_STRING_LEN);
+    };
+    if (is_previous_magic(copies_[0].main) ||
+        is_previous_magic(copies_[1].main)) {
+        if (!can_write_to_map_) {
+            MONAD_ABORT_PRINTF(
+                "Detected pre-dual-timeline DB (magic=%s), which requires "
+                "writable mapping to migrate to %s. Open with write access.",
+                detail::db_metadata::PREVIOUS_MAGIC,
+                detail::db_metadata::MAGIC);
+        }
+        for (auto &copy : copies_) {
+            auto *const m = copy.main;
+            if (!is_previous_magic(m)) {
+                continue;
+            }
+            auto const g = m->hold_dirty();
+            memset(&m->secondary_timeline, 0, sizeof(m->secondary_timeline));
+            std::atomic_signal_fence(std::memory_order_seq_cst);
+            memcpy(
+                m->magic,
+                detail::db_metadata::MAGIC,
+                detail::db_metadata::MAGIC_STRING_LEN);
+        }
+        LOG_INFO(
+            "Migrated DB metadata from {} to {}.",
+            detail::db_metadata::PREVIOUS_MAGIC,
+            detail::db_metadata::MAGIC);
+    }
+
+    // Version mismatch detection (for any other version that we don't migrate)
     constexpr unsigned magic_version_len = 3;
     constexpr unsigned magic_prefix_len =
         detail::db_metadata::MAGIC_STRING_LEN - magic_version_len;
@@ -235,6 +278,7 @@ DbMetadataContext::DbMetadataContext(AsyncIO &io)
     else {
         // Existing pool: map root offsets immediately
         map_root_offsets();
+        map_secondary_root_offsets();
     }
 }
 #if defined(__GNUC__) && !defined(__clang__)
@@ -306,6 +350,39 @@ void DbMetadataContext::map_root_offsets()
         copies_[0].root_offsets.size());
 }
 
+void DbMetadataContext::map_secondary_root_offsets()
+{
+    // Map the secondary timeline's root offset ring from cnv chunk 0's
+    // unused space, immediately after db_metadata (one copy per half-chunk).
+    // The assertion below verifies the chosen ring size fits.
+    static constexpr size_t SECONDARY_RING_CAPACITY = 65536; // 2^16
+    static constexpr size_t secondary_ring_bytes =
+        SECONDARY_RING_CAPACITY * sizeof(chunk_offset_t);
+
+    auto &cnv_chunk = io_->storage_pool().chunk(storage_pool::cnv, 0);
+    auto const fdr = cnv_chunk.read_fd();
+    auto const fdw = cnv_chunk.write_fd(0);
+    auto const secondary_offset = round_up_align<CPU_PAGE_BITS>(db_map_size_);
+    MONAD_ASSERT(
+        secondary_offset + secondary_ring_bytes <= cnv_chunk.capacity() / 2);
+
+    for (unsigned i = 0; i < 2; i++) {
+        auto const file_offset =
+            fdr.second + i * (cnv_chunk.capacity() / 2) + secondary_offset;
+        auto *ptr = ::mmap(
+            nullptr,
+            secondary_ring_bytes,
+            prot_,
+            mapflags_,
+            (can_write_to_map_ ? fdw : fdr).first,
+            off_t(file_offset));
+        MONAD_ASSERT(ptr != MAP_FAILED);
+        copies_[i].secondary_root_offsets = {
+            start_lifetime_as<chunk_offset_t>((chunk_offset_t *)ptr),
+            SECONDARY_RING_CAPACITY};
+    }
+}
+
 // Version metadata getters
 
 uint64_t DbMetadataContext::get_latest_finalized_version() const noexcept
@@ -573,13 +650,18 @@ chunk_offset_t DbMetadataContext::get_root_offset_at_version(
 
 DbMetadataContext::~DbMetadataContext()
 {
-    // munmap root_offsets
     for (auto &copy : copies_) {
         if (copy.root_offsets.data() != nullptr) {
             (void)::munmap(
                 copy.root_offsets.data(), copy.root_offsets.size_bytes());
             copy.root_offsets = {};
         }
+        if (copy.secondary_root_offsets.data() != nullptr) {
+            (void)::munmap(
+                copy.secondary_root_offsets.data(),
+                copy.secondary_root_offsets.size_bytes());
+            copy.secondary_root_offsets = {};
+        }
     }
     // munmap db_metadata
     if (copies_[0].main != nullptr) {
@@ -711,6 +793,13 @@ void DbMetadataContext::init_new_pool(
         detail::db_metadata::MAGIC_STRING_LEN);
 
     map_root_offsets();
+    map_secondary_root_offsets();
+    for (auto &copy : copies_) {
+        std::fill(
+            copy.secondary_root_offsets.begin(),
+            copy.secondary_root_offsets.end(),
+            INVALID_OFFSET);
+    }
     // Set history length, MUST be after root offsets are mapped
     if (history_len.has_value()) {
         update_history_length_metadata(*history_len);

category/mpt/db_metadata_context.hpp

@@ -22,6 +22,7 @@
 #include <category/core/detail/start_lifetime_as_polyfill.hpp>
 #include <category/mpt/config.hpp>
 #include <category/mpt/detail/db_metadata.hpp>
+#include <category/mpt/detail/timeline.hpp>
 #include <category/mpt/util.hpp>
 
 #include <atomic>
@@ -48,6 +49,7 @@ class DbMetadataContext
     {
         detail::db_metadata *main{nullptr};
         std::span<chunk_offset_t> root_offsets;
+        std::span<chunk_offset_t> secondary_root_offsets;
     };
 
     // Construct and mmap metadata from the given AsyncIO's storage pool.
@@ -133,6 +135,28 @@ class DbMetadataContext
                     root_offsets_chunks_.size());
             }
 
+            root_offsets_delegator(
+                uint64_t &version_lower_bound, uint64_t &next_version,
+                std::span<chunk_offset_t> root_offsets_chunks)
+                : version_lower_bound_(version_lower_bound)
+                , next_version_(next_version)
+                , root_offsets_chunks_(root_offsets_chunks)
+            {
+                MONAD_ASSERT_PRINTF(
+                    root_offsets_chunks_.size() == 0 ||
+                        root_offsets_chunks_.size() ==
+                            1ULL
+                                << (63 - std::countl_zero(
+                                             root_offsets_chunks_.size())),
+                    "root offsets chunks size is %lu, not a power of 2",
+                    root_offsets_chunks_.size());
+            }
+
+            bool empty() const noexcept
+            {
+                return root_offsets_chunks_.empty();
+            }
+
             size_t capacity() const noexcept
             {
                 return root_offsets_chunks_.size();
@@ -210,6 +234,32 @@ class DbMetadataContext
         return root_offsets_delegator{&copies_[which]};
     }
 
+    auto root_offsets(timeline_id const tid, unsigned const which = 0) const
+    {
+        using delegator = decltype(root_offsets(0));
+        auto const *m = &copies_[which];
+        if (tid == timeline_id::primary) {
+            return delegator{&copies_[which]};
+        }
+        return delegator{
+            m->main->secondary_timeline.version_lower_bound_,
+            m->main->secondary_timeline.next_version_,
+            m->secondary_root_offsets};
+    }
+
+    std::span<chunk_offset_t>
+    secondary_root_offsets(unsigned const which = 0) const noexcept
+    {
+        return copies_[which].secondary_root_offsets;
+    }
+
+    void swap_root_offsets_spans() noexcept
+    {
+        for (auto &copy : copies_) {
+            std::swap(copy.root_offsets, copy.secondary_root_offsets);
+        }
+    }
+
     // Version metadata getters/setters
     uint64_t get_latest_finalized_version() const noexcept;
     void set_latest_finalized_version(uint64_t version) noexcept;
@@ -287,6 +337,7 @@ class DbMetadataContext
     // Map root_offsets from cnv chunks. Called by the constructor for existing
     // pools, and by UpdateAux::init() after writing magic for new pools.
     void map_root_offsets();
+    void map_secondary_root_offsets();
 
     detail::db_metadata *main_mutable(unsigned const which = 0) noexcept
     {

category/mpt/detail/db_metadata.hpp

@@ -63,8 +63,11 @@ namespace detail
     // For the memory map of the first conventional chunk
     struct db_metadata
     {
-        static constexpr char const *MAGIC = "MONAD007";
+        static constexpr char const *MAGIC = "MONAD008";
         static constexpr unsigned MAGIC_STRING_LEN = 8;
+        // Previous magic supported via on-the-fly migration (see
+        // DbMetadataContext constructor).
+        static constexpr char const *PREVIOUS_MAGIC = "MONAD007";
 
         friend class MONAD_MPT_NAMESPACE::DbMetadataContext;
         friend class MONAD_MPT_NAMESPACE::UpdateAux;
@@ -156,8 +159,23 @@ namespace detail
         bytes32_t latest_voted_block_id;
         bytes32_t latest_proposed_block_id;
 
+        // Secondary timeline root offsets ring header. The ring data
+        // itself lives in cnv chunk 0's unused space (after db_metadata),
+        // not in separate cnv_chunks. active_ == 0 means inactive; the
+        // other fields are defined only when active_ != 0.
+        struct secondary_timeline_header_t
+        {
+            uint64_t version_lower_bound_;
+            uint64_t next_version_;
+            uint8_t active_; // nonzero = active
+            uint8_t reserved_[23];
+        } secondary_timeline;
+
+        static_assert(sizeof(secondary_timeline_header_t) == 40);
+
         // padding for adding future atomics without requiring DB reset
-        uint8_t future_variables_unused[4032];
+        uint8_t
+            future_variables_unused[4032 - sizeof(secondary_timeline_header_t)];
 
         // used to know if the metadata was being
         // updated when the process suddenly exited
@@ -508,13 +526,18 @@ namespace detail
         dest->root_offsets.next_version_ = 0; // INVALID_BLOCK_NUM
         auto const old_next_version = intr->root_offsets.next_version_;
         intr->root_offsets.next_version_ = 0; // INVALID_BLOCK_NUM
+        dest->secondary_timeline.next_version_ = 0;
+        auto const old_secondary_next = intr->secondary_timeline.next_version_;
+        intr->secondary_timeline.next_version_ = 0;
         atomic_memcpy((void *)dest, buffer, sizeof(db_metadata));
         atomic_memcpy(
             ((std::byte *)dest) + sizeof(db_metadata),
             ((std::byte const *)src) + sizeof(db_metadata),
             bytes - sizeof(db_metadata));
         std::atomic_ref<uint64_t>(dest->root_offsets.next_version_)
             .store(old_next_version, std::memory_order_release);
+        std::atomic_ref<uint64_t>(dest->secondary_timeline.next_version_)
+            .store(old_secondary_next, std::memory_order_release);
     };
 }
 

category/mpt/detail/timeline.hpp

@@ -0,0 +1,52 @@
+// Copyright (C) 2025 Category Labs, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <category/mpt/config.hpp>
+#include <category/mpt/util.hpp>
+
+#include <cstdint>
+#include <type_traits>
+
+MONAD_MPT_NAMESPACE_BEGIN
+
+enum class timeline_id : uint8_t
+{
+    primary = 0,
+    secondary = 1
+};
+
+static constexpr unsigned NUM_TIMELINES = 2;
+static_assert(
+    static_cast<unsigned>(timeline_id::secondary) + 1 == NUM_TIMELINES);
+
+/// Per-timeline compaction state. Each timeline maintains its own compaction
+/// boundary and stride. Disk growth tracking remains global since both
+/// timelines share the same fast/slow append rings.
+struct timeline_compaction_state
+{
+    compact_offset_pair compact_offsets{
+        MIN_COMPACT_VIRTUAL_OFFSET, MIN_COMPACT_VIRTUAL_OFFSET};
+    compact_virtual_chunk_offset_t compact_offset_range_fast_{
+        MIN_COMPACT_VIRTUAL_OFFSET};
+    compact_virtual_chunk_offset_t compact_offset_range_slow_{
+        MIN_COMPACT_VIRTUAL_OFFSET};
+    int64_t curr_upsert_auto_expire_version{0};
+};
+
+static_assert(std::is_trivially_copyable_v<timeline_compaction_state>);
+
+MONAD_MPT_NAMESPACE_END