From 0121bc06838ac47451fac8dde90805ac0c64f2bb Mon Sep 17 00:00:00 2001
From: Rongsong Shen <rshen@shenrs.eu>
Date: Thu, 4 Jun 2026 13:55:45 +0000
Subject: [PATCH] feat(ha-repl-hardening): add snapshot chunk fields to capnp
 schema (task 1.3)

Extend SnapshotTransfer struct from 2 to 6 fields:
- snapshotLsn (existing), chunkIndex, chunkOffset, totalSize,
  isLast, payload (existing)
No resumption fields per restart-on-reconnect policy.
---
 .kiro/specs/ha-repl-hardening/tasks.md |  2 +-
 src/include/typemap.h                  |  8 ++++++--
 src/schema/controller.capnp            | 13 +++++++++++--
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/.kiro/specs/ha-repl-hardening/tasks.md b/.kiro/specs/ha-repl-hardening/tasks.md
index f0fab31..103ed30 100644
--- a/.kiro/specs/ha-repl-hardening/tasks.md
+++ b/.kiro/specs/ha-repl-hardening/tasks.md
@@ -24,7 +24,7 @@
   - _Requirements: 5.1_
   - _Boundary: Wire Protocol (controller.capnp)_
 
-- [ ] 1.3 Add snapshot chunk fields to capnp schema
+- [x] 1.3 Add snapshot chunk fields to capnp schema
   - Add `checkpointLsn`, `chunkIndex`, `chunkOffset`, `totalSize`, `isLast` fields to the snapshot transfer message
   - No resumption fields — restart-on-reconnect policy means no snapshot progress state in `stateReport`
   - Regenerate capnp bindings; verify compilation
diff --git a/src/include/typemap.h b/src/include/typemap.h
index f3a70f6..61d1cb4 100644
--- a/src/include/typemap.h
+++ b/src/include/typemap.h
@@ -282,8 +282,12 @@ typedef struct {
 } upgrade_config_ack_t;
 
 typedef struct {
-    uint64_t    snapshot_lsn;
-    xce_data_t *payload;
+    uint64_t    snapshot_lsn;   /* checkpoint LSN this snapshot corresponds to */
+    xce_data_t *payload;        /* chunk payload (64 KB max) */
+    uint32_t    chunk_index;    /* 0-based chunk number */
+    uint64_t    chunk_offset;   /* byte offset in the full snapshot */
+    uint64_t    total_size;     /* total snapshot size in bytes */
+    int         is_last;        /* true (non-zero) for the final chunk */
 } snapshot_transfer_t;
 
 typedef struct wal_catchup_entry {
diff --git a/src/schema/controller.capnp b/src/schema/controller.capnp
index 49ce1c9..23f9838 100644
--- a/src/schema/controller.capnp
+++ b/src/schema/controller.capnp
@@ -829,9 +829,18 @@ struct UpgradeConfigAck $C.mapname("upgrade_config_ack_t") {
   success   @2 :Bool   $C.mapname("success");
 }
 
+# ── Snapshot chunk transfer (Req 4.1–4.2) ───────────────────────────
+# Used for OPCode_snapshotTransfer: full state snapshot transferred as
+# a sequence of fixed-size chunks (64 KB max each). Restart-on-reconnect
+# semantics — no resumption state needed. Fields @0 and @1 are preserved
+# for wire-protocol continuity; @2–@5 carry the chunk envelope.
 struct SnapshotTransfer $C.mapname("snapshot_transfer_t") {
-  snapshotLsn @0 :UInt64 $C.mapname("snapshot_lsn");
-  payload     @1 :Data   $C.mapname("payload");
+  snapshotLsn  @0 :UInt64 $C.mapname("snapshot_lsn");   # checkpoint LSN this snapshot corresponds to
+  payload      @1 :Data   $C.mapname("payload");         # chunk payload (64 KB max)
+  chunkIndex   @2 :UInt32 $C.mapname("chunk_index");     # 0-based chunk number
+  chunkOffset  @3 :UInt64 $C.mapname("chunk_offset");    # byte offset in the full snapshot
+  totalSize    @4 :UInt64 $C.mapname("total_size");      # total snapshot size in bytes
+  isLast       @5 :Bool   $C.mapname("is_last");         # true for the final chunk
 }
 
 struct WalCatchupEntry $C.mapname("wal_catchup_entry_t") {