refactor(domain): turn header into an immutable value type

The old header inherited from header_basis, mixed in hash_memoizer to
cache the block hash, and carried a mutable `validation` struct holding
height and median_time_past stamped from outside. The cache was a thread
hazard, the inheritance leaked basis internals, and the validation
struct was a side-channel for height/MTP that the value type should
never own.

Replace it with two interchangeable value types selected at compile
time via `KTH_USE_HEADER_MEMBERS`:

- header_raw (default): 80-byte contiguous storage, fields decoded on
  access. Wins on the IBD hot path — faster deserialization, zero-copy
  raw access for wire-handling code.
- header_members: traditional struct, field-per-member. Wins on
  repeated full-record access (wallets, explorers).

Both expose the same surface plus a free function `chain::hash(header)`
in lieu of the cached `header.hash()` member.

The validation side-channel is gone: block_pool and branch now read
height and MTP off the block's chain_state, which the validator
already populates. block_organizer no longer stamps the header.

C-API regenerated via kth-tools (no hand edits). The generator picks
up `chain::hash(header const&)` automatically thanks to a new
`extra_namespaces=['kth::domain::chain']` on the header config, so
`kth_chain_header_hash` is exposed as a normal accessor.

Caught while wiring up the tests, fixed in passing:
- block_entry::parent() returned `hash_digest const&` but the new
  header decodes previous_block_hash from raw bytes into a temporary
  — every caller was holding a dangling reference.
- Same dangle in header_organizer.cpp and internal_database test.

Old files (header.cpp, header_basis.cpp, hash_memoizer.hpp, original
message/header.{hpp,cpp}) are renamed to `.disabled` so any stragglers
trip the compiler instead of silently linking against legacy code.

Author: fpelliccioni

src/blockchain/include/kth/blockchain/pools/block_entry.hpp

@@ -34,7 +34,10 @@ struct KB_API block_entry {
     hash_digest const& hash() const;
 
     /// The hash table entry's parent (preceding block) hash.
-    hash_digest const& parent() const;
+    /// Returned by value: the new header value type decodes
+    /// `previous_block_hash()` from raw bytes into a temporary, so a
+    /// reference would dangle.
+    hash_digest parent() const;
 
     /// The hash table entry's child (succeeding block) hashes.
     hash_list const& children() const;

src/blockchain/src/interface/block_chain.cpp

@@ -185,7 +185,7 @@ bool block_chain::start(uint32_t disk_magic) {
         // Only genesis in DB - just add genesis to index
         auto const genesis = get_header(0);
         if (genesis) {
-            auto const hash = genesis->hash();
+            auto const hash = domain::chain::hash(*genesis);
             auto const [inserted, idx, capacity_warning] = header_index_.add(hash, *genesis);
             if ( ! inserted) {
                 spdlog::error("[blockchain] Failed to initialize header index with genesis block.");
@@ -214,7 +214,7 @@ bool block_chain::start(uint32_t disk_magic) {
 
             size_t height = from;
             for (auto const& header : *headers_result) {
-                auto const hash = header.hash();
+                auto const hash = domain::chain::hash(header);
                 auto const [inserted, idx, capacity_warning] = header_index_.add(hash, header);
                 if ( ! inserted && height > 0) {
                     // Genesis might already be added, ignore that case
@@ -404,7 +404,7 @@ ::asio::awaitable<code> block_chain::store_chunk(
     // Each block writes to its own index entry — safe without locks.
     for (size_t i = 0; i < n; ++i) {
         auto const& block = blocks[i];
-        auto const block_hash = block->header().hash();
+        auto const block_hash = domain::chain::hash(block->header());
         auto const idx = header_index_.find(block_hash);
         if (idx != header_index::null_index) {
             auto const& data_pos = (*positions)[i];
@@ -535,7 +535,7 @@ ::asio::awaitable<code> block_chain::store_block(
         }
 
         // 2. Update header_index with block file position
-        auto const block_hash = block->header().hash();
+        auto const block_hash = domain::chain::hash(block->header());
         auto const idx = header_index_.find(block_hash);
         if (idx != header_index::null_index) {
             header_index_.set_block_pos(idx, static_cast<int16_t>(pos.file), pos.pos);
@@ -867,7 +867,7 @@ std::expected<hash_digest, database::result_code> block_chain::get_block_hash(si
     if ( ! result) {
         return std::unexpected(result.error());
     }
-    return result->hash();
+    return domain::chain::hash(*result);
 }
 
 bool block_chain::header_exists(hash_digest const& block_hash) const {
@@ -1111,7 +1111,7 @@ block_chain::fetch_block_hash_timestamp(size_t height) const {
         co_return std::unexpected(error::not_found);
     }
 
-    co_return std::tuple{result->hash(), result->timestamp(), height};
+    co_return std::tuple{domain::chain::hash(*result), result->timestamp(), height};
 }
 
 // DEPRECATED: Block storage moved to flat files (blk*.dat)
@@ -1299,7 +1299,7 @@ block_chain::fetch_locator_block_hashes(get_blocks_const_ptr locator,
             break;
         }
         static auto const id = inventory::type_id::block;
-        hashes->inventories().emplace_back(id, result->hash());
+        hashes->inventories().emplace_back(id, domain::chain::hash(*result));
     }
 
     co_return hashes;
@@ -1369,7 +1369,7 @@ block_chain::fetch_block_locator(block::indexes const& heights) const {
         if ( ! result) {
             co_return std::unexpected(error::not_found);
         }
-        hashes.push_back(result->hash());
+        hashes.push_back(domain::chain::hash(*result));
     }
 
     co_return message;

src/blockchain/src/pools/block_entry.cpp

@@ -30,7 +30,7 @@ hash_digest const& block_entry::hash() const {
 }
 
 // Not callable if the entry is a search key.
-hash_digest const& block_entry::parent() const {
+hash_digest block_entry::parent() const {
     KTH_ASSERT(block_);
     return block_->header().previous_block_hash();
 }

src/blockchain/src/pools/block_organizer.cpp

@@ -168,10 +168,10 @@ ::asio::awaitable<code> block_organizer::organize(block_const_ptr block, bool he
 
     auto& top_block = branch->top()->validation;
     top_block.error = error::success;
-
-    auto& top_header = branch->top()->header().validation;
-    top_header.median_time_past = top_block.state->median_time_past();
-    top_header.height = branch->top_height();
+    // The header used to carry mutable validation.median_time_past /
+    // .height stamped here. The header is now a pure value type; both
+    // values are already available on the block's chain_state and the
+    // branch's top_height(), so we no longer mutate the header.
 
     auto const work = branch->work();
     auto const first_height = branch->height() + 1u;

src/blockchain/src/pools/block_pool.cpp

@@ -31,9 +31,14 @@ void block_pool::add(block_const_ptr valid_block) {
     ////KTH_ASSERT( ! block->validation.error);
     block_entry entry{ valid_block };
 
-    // Not all blocks will have validation state.
-    ////KTH_ASSERT(block->validation.state);
-    auto height = valid_block->header().validation.height;
+    // Height previously came from header().validation.height; the header
+    // is now a pure value type, so we read it from the block's chain_state
+    // which is populated by the validator before the block reaches the pool.
+    // Fall back to 0 to preserve the legacy semantics when an unvalidated
+    // block (no chain_state) is added — e.g. dedup-only test paths.
+    auto height = valid_block->validation.state
+        ? static_cast<size_t>(valid_block->validation.state->height())
+        : size_t{0};
     auto const& left = blocks_.left;
 
     // Caller ensure the entry does not exist by using get_path, but
@@ -94,7 +99,8 @@ void block_pool::remove(block_const_ptr_list_const_ptr accepted_blocks) {
 
         // Copy the entry so that it can be deleted and replanted with height.
         auto const copy = it->first;
-        auto const height = copy.block()->header().validation.height;
+        KTH_ASSERT(copy.block()->validation.state);
+        auto const height = static_cast<size_t>(copy.block()->validation.state->height());
         KTH_ASSERT(it->second == 0);
 
         // Critical Section
@@ -116,7 +122,9 @@ void block_pool::prune(hash_list const& hashes, size_t minimum_height) {
         auto const it = left.find(block_entry{ hash });
         KTH_ASSERT(it != left.end());
 
-        auto const height = it->first.block()->header().validation.height;
+        KTH_ASSERT(it->first.block()->validation.state);
+        auto const height = static_cast<size_t>(
+            it->first.block()->validation.state->height());
 
         // Delete all roots and expired non-roots and recurse their children.
         if (it->second != 0 || height < minimum_height) {

src/blockchain/src/pools/branch.cpp

@@ -124,7 +124,12 @@ uint32_t branch::height_at(size_t index) const {
 // private
 uint32_t branch::median_time_past_at(size_t index) const {
     KTH_ASSERT(index < size());
-    return (*blocks_)[index]->header().validation.median_time_past;
+    // MTP used to live on header.validation.median_time_past; the header
+    // is now a pure value type, so we read it from the block's chain_state
+    // (populated by the validator before the block reaches the branch).
+    auto const& block = *(*blocks_)[index];
+    KTH_ASSERT(block.validation.state);
+    return block.validation.state->median_time_past();
 }
 
 // TODO(legacy): absorb into the main chain for speed and code consolidation.

src/blockchain/src/pools/header_organizer.cpp

@@ -109,7 +109,7 @@ header_organize_result header_organizer::add_headers(domain::message::header::li
     // it matches an older block in our chain. If so, these are stale/duplicate headers
     // that can be silently skipped.
     if (!headers.empty()) {
-        auto const& first_prev_hash = headers.front().previous_block_hash();
+        auto const first_prev_hash = headers.front().previous_block_hash();
         spdlog::debug("[header_organizer] First header prev_hash: {}",
             encode_hash(first_prev_hash));
 
@@ -142,7 +142,7 @@ header_organize_result header_organizer::add_headers(domain::message::header::li
     for (auto const& header : headers) {
         // Compute hash first (needed for validation)
         KTH_STATS_TIME_START(hash);
-        auto const hash = header.hash();
+        auto const hash = domain::chain::hash(header);
         KTH_STATS_TIME_END(global_sync_stats(), hash, hash_time_ns, hash_calls);
 
         // Validate header with full chain-state validation

src/blockchain/src/validate/validate_header.cpp

@@ -33,7 +33,8 @@ code validate_header::check(domain::chain::header const& header) const {
     // Delegate to header's check() which validates:
     // 1. Proof of work (hash <= target derived from bits)
     // 2. Timestamp not too far in future (2 hours)
-    return header.check(retarget_);
+    auto const hash = domain::chain::hash(header);
+    return header.check(hash, retarget_);
 }
 
 // Chain-context validation
@@ -48,7 +49,7 @@ code validate_header::accept(domain::chain::header const& header, size_t height,
         return error::store_block_missing_parent;
     }
 
-    auto const hash = header.hash();
+    auto const hash = domain::chain::hash(header);
 
     // Validate against checkpoints
     if (is_checkpoint_conflict(hash, height)) {

src/blockchain/test/block_entry.cpp

@@ -36,8 +36,9 @@ TEST_CASE("block entry  construct2  default block hash  round trips", "[block en
 
 TEST_CASE("block entry  parent  hash42  expected", "[block entry tests]")
 {
-    auto const block = std::make_shared<domain::message::block>();
-    block->header().set_previous_block_hash(hash42);
+    domain::chain::header const hdr{0, hash42, null_hash, 0, 0, 0};
+    auto const block = std::make_shared<domain::message::block>(
+        hdr, domain::chain::transaction::list{});
     block_entry instance(block);
     REQUIRE(instance.parent() == hash42);
 }
@@ -65,8 +66,9 @@ TEST_CASE("block entry  add child  two  expected order", "[block entry tests]")
     auto const child1 = std::make_shared<const domain::message::block>();
     instance.add_child(child1);
 
-    auto const child2 = std::make_shared<domain::message::block>();
-    child2->header().set_previous_block_hash(hash42);
+    domain::chain::header const hdr{0, hash42, null_hash, 0, 0, 0};
+    auto const child2 = std::make_shared<domain::message::block>(
+        hdr, domain::chain::transaction::list{});
     instance.add_child(child2);
 
     REQUIRE(instance.children().size() == 2u);

src/blockchain/test/block_index_bench/benchmarks.cpp

@@ -74,19 +74,21 @@ class block_pool_fixture : public kth::blockchain::block_pool {
 
 // Create a minimal block with just a header (no transactions)
 kth::block_const_ptr create_kth_block(kth::hash_digest const& prev_hash, uint32_t height) {
-    // Create header with the given previous hash
-    kth::domain::chain::header hdr;
-    hdr.set_version(1);
-    hdr.set_previous_block_hash(prev_hash);
-    hdr.set_merkle(kth::null_hash);  // Empty merkle
-    hdr.set_timestamp(1231006505 + height * 600);  // ~10 min per block
-    hdr.set_bits(0x1d00ffff);
-    hdr.set_nonce(height);
-
-    // Set validation height (required by block_pool)
-    hdr.validation.height = height;
-
-    // Create block with empty transactions (just header)
+    // Header is now a value type with no setters and no validation struct.
+    // Pass every field through the 6-arg ctor.
+    kth::domain::chain::header const hdr{
+        /*version*/   1u,
+        /*prev*/      prev_hash,
+        /*merkle*/    kth::null_hash,
+        /*timestamp*/ uint32_t(1231006505u + height * 600u),  // ~10 min per block
+        /*bits*/      0x1d00ffffu,
+        /*nonce*/     height,
+    };
+
+    // The previous benchmark stamped height onto hdr.validation; block_pool
+    // now reads height from block.validation.state. This benchmark exercises
+    // the header_index path which does not consult block.validation.state,
+    // so no extra setup is needed here.
     auto block = std::make_shared<kth::domain::message::block>(
         hdr,
         kth::domain::chain::transaction::list{}