feat(storage): verify snapshot suffix recovery

Replay post-snapshot history through an independent recovered ledger and require its final state and root to match authoritative full-genesis replay. Cover genesis, behind-head, and head snapshots across restart.\n\nRefs #11

Author: kaikisegfault

docs/architecture/sqlite-ledger.md

@@ -35,9 +35,12 @@ verifies that the durable metadata head equals the owned ledger, independently
 decodes the candidate bytes, and atomically replaces the one retained snapshot.
 It returns the exact durably stored payload. Opening independently decodes that
 snapshot and compares its complete state and root at the same height reached by
-authoritative full-genesis replay. A retained snapshot may precede the current
-head after later blocks; suffix replay from that snapshot remains a separate
-recovery path.
+authoritative full-genesis replay. It then starts a second ledger from that
+independently restored snapshot, re-queries and replays only later block and
+journal rows, compares every suffix transaction ID, receipt, root, header, and
+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.
 
 The public header exposes no SQLite handle or SQL type. `SQLiteLedger` is
 move-constructible but not copyable or assignable. It owns the live
@@ -131,7 +134,8 @@ before the completed adapter is returned.
 
 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. Snapshot-plus-suffix recovery,
-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.
+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.

docs/project/current-state.md

@@ -1,6 +1,6 @@
 # Current state
 
-Last updated: 2026-07-24
+Last updated: 2026-07-25
 
 ## Phase
 
@@ -249,18 +249,28 @@ the active roadmap slice.
   parameter, ordering, conservation and root failures; replaces a height-zero
   snapshot at height two; reopens across an older snapshot; and rejects corrupt
   row projections or multiple retained snapshots.
-- The Clang sanitizer preset now includes a fourth bounded libFuzzer smoke
-  target for raw and structured snapshot bytes with a valid seed. Its
-  completion evidence is pending the exact-commit GitHub matrix.
+- The Clang sanitizer preset includes a fourth bounded libFuzzer smoke target
+  for raw and structured snapshot bytes with a valid seed. PR #15 merged the
+  snapshot slice as `63ff68f`; exact-candidate Actions run 30163985474 and
+  post-merge `main` run 30164137810 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.
+- Opening now starts a second recovery ledger from the independently decoded
+  latest snapshot, re-queries and replays only its later block and journal
+  rows, compares every suffix transaction ID, receipt, root, header, and block
+  ID, and requires the recovered state and root to equal authoritative full
+  genesis replay. Restart coverage exercises genesis, behind-head, and
+  current-head snapshots, including nonempty and empty suffixes. Focused GCC
+  debug verification passes this path together with both existing SQLite test
+  targets, 3/3.
 
 ## Exact next action
 
 Continue issue #11:
 
-> Start recovery from the latest independently verified snapshot, replay only
-> its retained journal suffix, compare every suffix output and the final head
-> with authoritative full-genesis replay, and add restart coverage for
-> snapshots before and at the current head.
+> 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.
 
 ## Open autonomous decisions
 

src/storage/sqlite_history_replay_v1.cpp

@@ -206,6 +206,39 @@ void replay_block_row(
       resulting_root, header, block_id);
 }
 
+void require_same_head(
+    const pv1::Ledger& recovered,
+    const pv1::Ledger& authoritative) {
+  const auto recovered_root = recovered.current_state_root();
+  const auto authoritative_root =
+      authoritative.current_state_root();
+  if (recovered.state() != authoritative.state() ||
+      !std::holds_alternative<pv1::StateRoot>(recovered_root) ||
+      !std::holds_alternative<pv1::StateRoot>(authoritative_root) ||
+      std::get<pv1::StateRoot>(recovered_root) !=
+          std::get<pv1::StateRoot>(authoritative_root)) {
+    fail(SQLiteLedgerError::state_mismatch);
+  }
+}
+
+void replay_snapshot_suffix(
+    Connection& connection,
+    const DecodedSnapshotV1& snapshot,
+    const pv1::Ledger& authoritative) {
+  pv1::Ledger recovered(snapshot.ledger);
+  Statement blocks = connection.prepare(
+      "SELECT height, previous_state_root, transaction_root, "
+      "resulting_state_root, admitted_count, header, block_id "
+      "FROM blocks WHERE height>? ORDER BY height");
+  const auto snapshot_height =
+      encode_u64(snapshot.ledger.state().height);
+  blocks.bind_blob(1, snapshot_height);
+  while (checked_step(blocks) == SQLITE_ROW) {
+    replay_block_row(connection, blocks, recovered);
+  }
+  require_same_head(recovered, authoritative);
+}
+
 }  // namespace
 
 pv1::Ledger replay_history_v1(
@@ -228,6 +261,9 @@ pv1::Ledger replay_history_v1(
   if (snapshot && !snapshot_matched) {
     fail(SQLiteLedgerError::state_mismatch);
   }
+  if (snapshot) {
+    replay_snapshot_suffix(connection, *snapshot, ledger);
+  }
   return ledger;
 }
 

tests/storage/snapshot_v1_test.cpp

@@ -384,9 +384,20 @@ void verify_persistence(
   {
     auto reopened = take_sqlite_ledger(
         ps::open_sqlite_ledger(files.path(), genesis),
-        "older snapshot plus full replay rejected");
+        "genesis snapshot suffix replay rejected");
     pv::require(reopened.read_head() == ledger_head(expected),
-                "older snapshot changed replay head");
+                "genesis snapshot suffix changed replay head");
+    const auto height_one_snapshot = take_snapshot(
+        reopened.create_snapshot(),
+        "height-one snapshot persistence failed");
+    const auto expected_height_one_snapshot = take_encoded(
+        ps::encode_snapshot_v1(expected),
+        "expected height-one snapshot failed");
+    pv::require(
+        height_one_snapshot ==
+            expected_height_one_snapshot.payload,
+        "height-one snapshot bytes changed");
+
     const std::vector<p::Bytes> empty;
     auto expected_block = expected.apply_block(2, empty);
     pv::require(
@@ -396,6 +407,14 @@ void verify_persistence(
     pv::require(
         std::holds_alternative<p::BlockCommit>(actual_block),
         "stored empty block rejected");
+  }
+
+  {
+    auto reopened = take_sqlite_ledger(
+        ps::open_sqlite_ledger(files.path(), genesis),
+        "height-one snapshot suffix replay rejected");
+    pv::require(reopened.read_head() == ledger_head(expected),
+                "height-one snapshot suffix changed replay head");
     const auto payload = take_snapshot(
         reopened.create_snapshot(), "head snapshot replacement failed");
     const auto expected_snapshot = take_encoded(