feat(storage): export portable ledger archives

Author: kaikisegfault

CMakeLists.txt

@@ -163,6 +163,8 @@ target_include_directories(
 add_library(
   protocol_storage
   STATIC
+    src/storage/archive_v1.cpp
+    src/storage/sqlite_archive_v1.cpp
     src/storage/sqlite_connection.cpp
     src/storage/sqlite_block_store_v1.cpp
     src/storage/sqlite_history_replay_v1.cpp
@@ -245,6 +247,10 @@ add_executable(
   storage_snapshot_v1_tests
   tests/storage/snapshot_v1_test.cpp
 )
+add_executable(
+  storage_archive_v1_tests
+  tests/storage/archive_v1_test.cpp
+)
 target_link_libraries(
   storage_sqlite_ledger_tests
   PRIVATE
@@ -263,6 +269,12 @@ target_link_libraries(
     protocol_storage
     protocol_stack_sqlite
 )
+target_link_libraries(
+  storage_archive_v1_tests
+  PRIVATE
+    protocol_storage
+    protocol_stack_sqlite
+)
 
 set(
   PROTOCOL_STACK_TARGETS
@@ -283,6 +295,7 @@ set(
   storage_sqlite_ledger_tests
   storage_sqlite_history_tests
   storage_snapshot_v1_tests
+  storage_archive_v1_tests
 )
 if(PROTOCOL_STACK_ENABLE_FUZZING)
   add_library(
@@ -312,6 +325,7 @@ if(PROTOCOL_STACK_ENABLE_FUZZING)
   add_library(
     protocol_storage_fuzz
     STATIC
+      src/storage/archive_v1.cpp
       src/storage/snapshot_v1.cpp
   )
   target_include_directories(
@@ -328,6 +342,15 @@ if(PROTOCOL_STACK_ENABLE_FUZZING)
     storage_snapshot_fuzz
     tests/fuzz/snapshot_fuzz.cpp
   )
+  add_executable(
+    storage_archive_fuzz
+    tests/fuzz/archive_fuzz.cpp
+  )
+  target_link_libraries(
+    storage_archive_fuzz
+    PRIVATE
+      protocol_storage_fuzz
+  )
   target_link_libraries(
     storage_snapshot_fuzz
     PRIVATE
@@ -343,6 +366,7 @@ if(PROTOCOL_STACK_ENABLE_FUZZING)
     kernel_genesis_fuzz
     protocol_storage_fuzz
     storage_snapshot_fuzz
+    storage_archive_fuzz
   )
 endif()
 
@@ -379,6 +403,7 @@ if(PROTOCOL_STACK_ENABLE_FUZZING)
       kernel_genesis_fuzz
       protocol_storage_fuzz
       storage_snapshot_fuzz
+      storage_archive_fuzz
   )
     target_compile_options(
       ${protocol_stack_fuzz_target}
@@ -393,6 +418,7 @@ if(PROTOCOL_STACK_ENABLE_FUZZING)
       kernel_address_fuzz
       kernel_genesis_fuzz
       storage_snapshot_fuzz
+      storage_archive_fuzz
   )
     target_link_options(
       ${protocol_stack_fuzz_executable}
@@ -512,6 +538,13 @@ add_test(
     "${PROJECT_SOURCE_DIR}/test-vectors/ledger-transition-v1.txt"
     "${CMAKE_CURRENT_BINARY_DIR}/storage-snapshot-v1-test"
 )
+add_test(
+  NAME storage-archive-v1
+  COMMAND
+    storage_archive_v1_tests
+    "${PROJECT_SOURCE_DIR}/test-vectors/ledger-transition-v1.txt"
+    "${CMAKE_CURRENT_BINARY_DIR}/storage-archive-v1-test"
+)
 set_tests_properties(
   protocol-primitives-python
   ledger-transition-python
@@ -561,11 +594,21 @@ if(PROTOCOL_STACK_ENABLE_FUZZING)
       -max_len=4096
       -len_control=0
   )
+  add_test(
+    NAME storage-archive-fuzz-smoke
+    COMMAND
+      storage_archive_fuzz
+      -seed=824311
+      -runs=512
+      -max_len=16384
+      -len_control=0
+  )
   set_tests_properties(
     kernel-admission-fuzz-smoke
     kernel-address-fuzz-smoke
     kernel-genesis-fuzz-smoke
     storage-snapshot-fuzz-smoke
+    storage-archive-fuzz-smoke
     PROPERTIES
       LABELS fuzz
       TIMEOUT 60

docs/architecture/sqlite-ledger.md

@@ -30,6 +30,17 @@ before account allocation, checks the SHA-256 domain-separated digest, requires
 strict account ordering, validates caller-trusted immutable parameters, and
 restores through the kernel's state-invariant and root checks.
 
+The public engine-independent archive codec implements ADR 0007's exact
+`PSAR` version-one bytes. The encoder accepts canonical genesis, contiguous
+canonical block outputs and admitted transaction records, plus a head
+snapshot. It independently loads genesis, replays every admitted block through
+the kernel, exact-compares transaction IDs, receipts, headers and block IDs,
+and requires the decoded snapshot to equal the replayed head before emitting
+bytes. The decoder bounds all attacker-controlled lengths and counts before
+allocation or advancement, never reserves from the declared block count,
+rejects non-exact framing, verifies the archive digest, and performs the same
+complete semantic replay.
+
 `SQLiteLedger::create_snapshot` serializes with reads and block application,
 verifies that the durable metadata head equals the owned ledger, independently
 decodes the candidate bytes, and atomically replaces the one retained snapshot.
@@ -42,6 +53,14 @@ block ID, and requires the recovered state and root to equal authoritative full
 replay. A snapshot at the current head exercises the same path with an empty
 suffix.
 
+`SQLiteLedger::export_archive` holds the adapter guard and one SQLite read
+transaction while it fully validates the durable ledger against
+caller-trusted genesis and the owned head. It creates a fresh snapshot of that
+verified head, then reads every block and admitted transaction in explicit
+height and ordinal order with exact width, count, and contiguity checks. The
+public codec replays that independently projected archive before export
+returns. Export does not change the retained database snapshot.
+
 The public header exposes no SQLite handle or SQL type. `SQLiteLedger` is
 move-constructible but not copyable or assignable. It owns the live
 `protocol::v1::Ledger`, serialized connection, normalized path, exact canonical
@@ -132,10 +151,9 @@ before the completed adapter is returned.
 
 ## Remaining issue 11 work
 
-The ordinary durable commit, full-genesis-replay path, canonical snapshot
-codec, atomic latest-snapshot persistence, and independent snapshot validation
-at its recorded replay height are implemented. Independent snapshot-plus-suffix
-recovery reaches the identical authoritative head. Portable export/import,
-automatic reopen after an ambiguous commit result, fault injection around
-every commit phase, long seeded restart sequences, and final issue closure
-remain.
+The ordinary durable commit, full-genesis-replay path, canonical snapshot and
+archive codecs, atomic latest-snapshot persistence, independent
+snapshot-plus-suffix recovery, and portable export are implemented. Portable
+import into a new database, automatic reopen after an ambiguous commit result,
+fault injection around every commit phase, long seeded restart sequences, and
+final issue closure remain.

docs/project/current-state.md

@@ -8,8 +8,9 @@ M1 — Sovereign Devnet Alpha. The deterministic in-memory ledger kernel is
 merged and verified. The owning storage adapter can now durably create and
 validate a height-zero ledger, atomically persist a complete block, and reopen
 the identical head through full genesis replay. Deterministic multi-block
-restart coverage is complete; snapshots, fault injection, and recovery remain
-the active roadmap slice.
+restart, snapshot recovery, and portable export are complete; archive import,
+fault injection, and ambiguous-commit recovery remain the active roadmap
+slice.
 
 ## Verified facts
 
@@ -263,14 +264,40 @@ the active roadmap slice.
   current-head snapshots, including nonempty and empty suffixes. Focused GCC
   debug verification passes this path together with both existing SQLite test
   targets, 3/3.
+- PR #16 merged snapshot-plus-suffix recovery as `3102adf`; exact-candidate
+  Actions run 30164373238 and post-merge `main` run 30164507913 both passed GCC
+  and Clang debug plus ASan/UBSan. The first three jobs passed 17/17 tests and
+  Clang ASan/UBSan passed 21/21 including all four fuzz targets.
+- The public engine-independent archive codec implements ADR 0007's exact
+  `PSAR` version-one framing. It bounds hostile lengths and counts before
+  allocation or advancement, verifies the domain-separated digest, loads
+  canonical genesis, replays every admitted block, exact-compares transaction
+  IDs, receipts, headers and block IDs, and requires the head snapshot to
+  equal the replayed state and root.
+- `SQLiteLedger::export_archive` serializes with block application and holds
+  one read transaction while it fully validates the durable ledger against
+  caller-trusted genesis and the owned head, creates a fresh head snapshot,
+  reads history in explicit height and ordinal order with exact projection
+  checks, and semantically validates the projected archive before returning
+  bytes. Export does not alter the retained database snapshot.
+- Focused GCC debug verification passes the archive codec/export test together
+  with the existing SQLite ledger, history, and snapshot targets, 4/4. The
+  archive suite freezes a 3,745-byte one-block fixture and digest; covers
+  deterministic zero-block, empty-block, and populated-block round trips,
+  truncation, trailing bytes, hostile counts and lengths, wrong
+  magic/version/digest, history and snapshot corruption; and proves
+  deterministic multi-block export across repeated calls and reopen. The Clang
+  sanitizer configuration exposes a fifth bounded libFuzzer target with raw,
+  structured, and valid archive seeds.
 
 ## Exact next action
 
 Continue issue #11:
 
-> Implement the canonical version-one portable archive codec and serialized
-> export from one verified database head, with overflow-safe framing, digest
-> verification, and exact history-plus-snapshot projections before import.
+> Implement portable archive import only into a new database: validate the
+> complete archive before touching the target path, persist its exact history,
+> materialized head, and snapshot atomically, then reopen through full replay
+> and prove byte-identical export.
 
 ## Open autonomous decisions
 

include/protocol/storage/archive_v1.hpp

@@ -0,0 +1,71 @@
+#pragma once
+
+#include "protocol/v1/ledger.hpp"
+
+#include <cstdint>
+#include <span>
+#include <variant>
+#include <vector>
+
+namespace protocol::storage {
+
+enum class ArchiveV1Error : std::uint8_t {
+  malformed = 1,
+  unsupported_version = 2,
+  size_overflow = 3,
+  digest_mismatch = 4,
+  invalid_genesis = 5,
+  invalid_history = 6,
+  snapshot_mismatch = 7,
+};
+
+struct ArchiveTransactionV1 {
+  protocol::v1::Bytes transaction;
+  protocol::v1::TransactionId transaction_id;
+  protocol::v1::Bytes receipt;
+
+  bool operator==(const ArchiveTransactionV1&) const = default;
+};
+
+struct ArchiveBlockV1 {
+  protocol::v1::Bytes header;
+  protocol::v1::BlockId block_id;
+  std::vector<ArchiveTransactionV1> transactions;
+
+  bool operator==(const ArchiveBlockV1&) const = default;
+};
+
+struct ArchiveV1Data {
+  protocol::v1::Bytes canonical_genesis;
+  std::vector<ArchiveBlockV1> blocks;
+  protocol::v1::Bytes head_snapshot;
+
+  bool operator==(const ArchiveV1Data&) const = default;
+};
+
+struct EncodedArchiveV1 {
+  protocol::v1::Bytes payload;
+  protocol::v1::Hash digest;
+
+  bool operator==(const EncodedArchiveV1&) const = default;
+};
+
+struct DecodedArchiveV1 {
+  ArchiveV1Data data;
+  protocol::v1::Ledger ledger;
+  protocol::v1::StateRoot state_root;
+  protocol::v1::Hash digest;
+};
+
+using ArchiveV1EncodeResult =
+    std::variant<EncodedArchiveV1, ArchiveV1Error>;
+using ArchiveV1DecodeResult =
+    std::variant<DecodedArchiveV1, ArchiveV1Error>;
+
+ArchiveV1EncodeResult encode_archive_v1(
+    const ArchiveV1Data& archive);
+
+ArchiveV1DecodeResult decode_archive_v1(
+    std::span<const std::uint8_t> payload);
+
+}  // namespace protocol::storage

include/protocol/storage/sqlite_ledger.hpp

@@ -40,6 +40,9 @@ using SQLiteBlockResult = std::variant<
 using SQLiteSnapshotResult = std::variant<
     protocol::v1::Bytes,
     SQLiteLedgerError>;
+using SQLiteArchiveResult = std::variant<
+    protocol::v1::Bytes,
+    SQLiteLedgerError>;
 
 class SQLiteLedger {
  public:
@@ -55,6 +58,7 @@ class SQLiteLedger {
       std::uint64_t height,
       std::span<const protocol::v1::Bytes> raw_transactions);
   SQLiteSnapshotResult create_snapshot();
+  SQLiteArchiveResult export_archive();
 
  private:
   struct Impl;