feat(versioning): snapshot corpus per spec version

A frozen spec is only meaningful if it's paired with the corpus that was current at release time — otherwise a v0.1.0 reader follows "see corpus/payloads/ack/" and lands on a file whose test vectors may have changed since v0.1.0 was cut. Three changes: 1. `cut-version` now copies BOTH src/ AND corpus/ into the snapshot directory. A release is the pair, not just the text. 2. The corpus URL rewriting in cut-version now retargets /tree/main/corpus -> /tree/main/versions/<v>/corpus (and the blob variant). This lets the link resolve on GitHub from main alone — no git tag required, since the frozen copy is a real path under main. Downgrades the "tag is REQUIRED" message from last commit back to "optionally tag the commit". 3. The frozen corpus's spec_ref fields get rewritten too: from `src/04-payload-ack.md` to `versions/<v>/04-payload-ack.md`, so a reader following a test vector lands on the spec text the vector was paired with at release time. versions/v0.1.0/ regenerated from scratch via `just cut-version v0.1.0` to pick up the corpus snapshot + the new sed patterns. The release is now self-consistent: v0.1.0 spec links go to v0.1.0 corpus, which links back to v0.1.0 spec. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:38:02 -06:00
1 parent f83d4088e3
commit 9232c16f7c
@@ -0,0 +1,122 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "ACK Payload - Basic",
+  "spec_ref": "versions/v0.1.0/04-payload-ack.md",
+  "protocol_version": 0,
+  "description": "Basic ACK payload encoding/decoding tests with various CRC values.",
+  "vectors": [
+    {
+      "id": "ack-001",
+      "description": "ACK with CRC 0xDEADBEEF",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "ack_crc": "DEADBEEF"
+        }
+      },
+      "binary": "0D 00 EFBEADDE",
+      "notes": "CRC 0xDEADBEEF stored as little-endian: EF BE AD DE."
+    },
+    {
+      "id": "ack-002",
+      "description": "ACK with CRC 0x00000001",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "ack_crc": "00000001"
+        }
+      },
+      "binary": "0D 00 01000000"
+    },
+    {
+      "id": "ack-003",
+      "description": "ACK with CRC 0x12345678",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "ack_crc": "12345678"
+        }
+      },
+      "binary": "0D 00 78563412"
+    },
+    {
+      "id": "ack-004",
+      "description": "ACK via direct routing with path",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 2,
+          "hashes": [
+            "AA",
+            "BB"
+          ]
+        },
+        "payload": {
+          "ack_crc": "CAFEBABE"
+        }
+      },
+      "binary": "0E 02 AABB BEBAFECA",
+      "notes": "Direct routed ACK. CRC 0xCAFEBABE as LE = BEBAFECA."
+    },
+    {
+      "id": "ack-005",
+      "description": "ACK with 2-byte hash path",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 2,
+          "hash_count": 1,
+          "hashes": [
+            "AABB"
+          ]
+        },
+        "payload": {
+          "ack_crc": "00000000"
+        }
+      },
+      "binary": "0E 41 AABB 00000000",
+      "notes": "path_len=0x41: hash_size=2, count=1."
+    }
+  ]
+}
@@ -0,0 +1,115 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "ACK Payload - Boundary Values",
+  "spec_ref": "versions/v0.1.0/04-payload-ack.md",
+  "protocol_version": 0,
+  "description": "ACK CRC boundary value tests including all-zeros, all-ones, and single-bit patterns.",
+  "vectors": [
+    {
+      "id": "ack-bnd-001",
+      "description": "ACK CRC all zeros",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "ack_crc": "00000000"
+        }
+      },
+      "binary": "0D 00 00000000"
+    },
+    {
+      "id": "ack-bnd-002",
+      "description": "ACK CRC all ones",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "ack_crc": "FFFFFFFF"
+        }
+      },
+      "binary": "0D 00 FFFFFFFF"
+    },
+    {
+      "id": "ack-bnd-003",
+      "description": "ACK CRC 0x80000000 (high bit set)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "ack_crc": "80000000"
+        }
+      },
+      "binary": "0D 00 00000080"
+    },
+    {
+      "id": "ack-bnd-004",
+      "description": "ACK CRC 0x00000080 (byte boundary)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "ack_crc": "00000080"
+        }
+      },
+      "binary": "0D 00 80000000"
+    },
+    {
+      "id": "ack-bnd-005",
+      "description": "ACK CRC 0x01000000",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "ack",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "ack_crc": "01000000"
+        }
+      },
+      "binary": "0D 00 00000001",
+      "notes": "Tests that 0x01000000 LE = 00 00 00 01, not confused with 0x00000001."
+    }
+  ]
+}
@@ -0,0 +1,128 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Advertisement App Data - Combined Optional Fields",
+  "spec_ref": "versions/v0.1.0/05-payload-advert.md",
+  "protocol_version": 0,
+  "description": "Tests app_data with multiple optional fields present simultaneously. Fields appear in order: flags, location (lat+lon), feat1, feat2, name.",
+  "vectors": [
+    {
+      "id": "adc-001",
+      "description": "Chat node with location + feat1 + name",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 177,
+            "latitude": 37774900,
+            "longitude": -122419400,
+            "feat1": 256,
+            "name": "Node1"
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB B1 34664002 3807B4F8 0001 4E6F646531",
+      "notes": "flags=0xB1=10110001: type=Chat(1), has_location(bit4), has_feat1(bit5), has_name(bit7). No feat2 (bit6=0). feat1=256=0x0100 LE=0001. Name 'Node1' = 4E6F646531."
+    },
+    {
+      "id": "adc-002",
+      "description": "Repeater with all optional fields",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 242,
+            "latitude": 0,
+            "longitude": 0,
+            "feat1": 1,
+            "feat2": 2,
+            "name": "RPT"
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB F2 00000000 00000000 0100 0200 525054",
+      "notes": "flags=0xF2=11110010: type=Repeater(2), all optional fields present. feat1=1 LE=0100, feat2=2 LE=0200, name='RPT'=525054."
+    },
+    {
+      "id": "adc-003",
+      "description": "Node with name only (no location or features)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 129,
+            "name": "Hi"
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 81 4869",
+      "notes": "flags=0x81=10000001: type=Chat(1), has_name(bit7) only. name='Hi'=4869."
+    },
+    {
+      "id": "adc-004",
+      "description": "Node with feat2 only (no location, feat1, or name)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 65,
+            "feat2": 65535
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 41 FFFF",
+      "notes": "flags=0x41=01000001: type=Chat(1), has_feat2(bit6). feat2=65535=0xFFFF."
+    }
+  ]
+}
@@ -0,0 +1,96 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Advertisement App Data - Location",
+  "spec_ref": "versions/v0.1.0/05-payload-advert.md",
+  "protocol_version": 0,
+  "description": "Tests app_data with location fields (latitude and longitude as int32_le × 1,000,000).",
+  "vectors": [
+    {
+      "id": "adl-001",
+      "description": "Chat node with location: San Francisco (37.7749, -122.4194)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 17,
+            "latitude": 37774900,
+            "longitude": -122419400
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 11 34664002 3807B4F8",
+      "notes": "flags=0x11: type=Chat(1), has_location(bit 4). Lat 37774900=0x02406634 LE=34664002. Lon -122419400=0xF8B40738 LE=3807B4F8."
+    },
+    {
+      "id": "adl-002",
+      "description": "Repeater with location: equator/prime meridian (0, 0)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 18,
+            "latitude": 0,
+            "longitude": 0
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 12 00000000 00000000",
+      "notes": "flags=0x12: type=Repeater(2), has_location. Both coords zero."
+    },
+    {
+      "id": "adl-003",
+      "description": "Sensor with negative latitude: south pole (-90, 0)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 20,
+            "latitude": -90000000,
+            "longitude": 0
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 14 80B5A2FA 00000000",
+      "notes": "flags=0x14: type=Sensor(4), has_location. Lat -90000000=0xFAA2B580 LE=80B5A2FA. Lon 0."
+    }
+  ]
+}
@@ -0,0 +1,140 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Advertisement App Data - Node Types",
+  "spec_ref": "versions/v0.1.0/05-payload-advert.md",
+  "protocol_version": 0,
+  "description": "Tests all defined node types in the app_data flags field (bits 0-3). Uses a common pub_key, zero timestamp, and zero signature for structural testing.",
+  "vectors": [
+    {
+      "id": "adt-001",
+      "description": "App data type: None (0)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 0
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 00",
+      "notes": "flags=0x00: type=None(0), no optional fields."
+    },
+    {
+      "id": "adt-002",
+      "description": "App data type: Chat (1)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 1
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 01"
+    },
+    {
+      "id": "adt-003",
+      "description": "App data type: Repeater (2)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 2
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 02"
+    },
+    {
+      "id": "adt-004",
+      "description": "App data type: Room (3)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 3
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 03"
+    },
+    {
+      "id": "adt-005",
+      "description": "App data type: Sensor (4)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+          "timestamp": 0,
+          "signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+          "app_data": {
+            "flags": 4
+          }
+        }
+      },
+      "binary": "11 00 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 00000000 BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB 04"
+    }
+  ]
+}
@@ -0,0 +1,88 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Advertisement Payload - Basic Structure",
+  "spec_ref": "versions/v0.1.0/05-payload-advert.md",
+  "protocol_version": 0,
+  "description": "Tests the basic structure of advertisement payloads: pub_key(32) + timestamp(4) + signature(64) + optional app_data. Uses synthetic signature bytes since signature verification requires real Ed25519 operations (see signature-verify.json for verifiable vectors).",
+  "vectors": [
+    {
+      "id": "adv-001",
+      "description": "Minimal advertisement: pub_key + timestamp + signature, no app_data",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20",
+          "timestamp": 1700000000,
+          "signature": "A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0"
+        }
+      },
+      "binary": "11 00 0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20 00F15365 A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0",
+      "notes": "Header: 0x11 = ADVERT+FLOOD. Timestamp 1700000000 = 0x6553F100 LE = 00F15365. Payload: 32+4+64 = 100 bytes."
+    },
+    {
+      "id": "adv-002",
+      "description": "Advertisement with 1-byte app_data",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "pub_key": "0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20",
+          "timestamp": 1700000000,
+          "signature": "A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0",
+          "app_data": {
+            "flags": 1
+          }
+        }
+      },
+      "binary": "11 00 0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20 00F15365 A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0 01",
+      "notes": "flags=0x01: type=Chat(1), no optional fields. Payload: 101 bytes."
+    },
+    {
+      "id": "adv-003",
+      "description": "Advertisement with path (3 hops, direct routing)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "advert",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 3,
+          "hashes": [
+            "AA",
+            "BB",
+            "CC"
+          ]
+        },
+        "payload": {
+          "pub_key": "0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20",
+          "timestamp": 0,
+          "signature": "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
+        }
+      },
+      "binary": "11 03 AABBCC 0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20 00000000 0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+      "notes": "Timestamp=0 and zero signature for structural testing."
+    }
+  ]
+}
@@ -0,0 +1,85 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Anonymous Request Payload",
+  "spec_ref": "versions/v0.1.0/07-payload-anon-req.md",
+  "protocol_version": 0,
+  "description": "Tests anonymous request payload: dest_hash(1) + sender_pub_key(32) + cipher_mac(2) + ciphertext.",
+  "vectors": [
+    {
+      "id": "anon-001",
+      "description": "Anonymous request with known keys",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "anon_req",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "sender_pub_key": "404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F",
+          "cipher_mac": "F4B4",
+          "ciphertext": "908A4FC137435774D0BB603F55A06069"
+        }
+      },
+      "binary": "1D 00 AB 404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F F4B4 908A4FC137435774D0BB603F55A06069",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "416E6F6E526571"
+      },
+      "notes": "Header 0x1D = ANON_REQ(7)+FLOOD(1). Payload: dest_hash(1) + pub_key(32) + mac(2) + ct(16) = 51 bytes. Plaintext 'AnonReq' (7 bytes)."
+    },
+    {
+      "id": "anon-002",
+      "description": "Anonymous request with tampered MAC",
+      "type": "invalid",
+      "binary": "1D 00 AB 404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F 0000 908A4FC137435774D0BB603F55A06069",
+      "expected_error": "mac_invalid",
+      "notes": "MAC zeroed. Verification must fail."
+    },
+    {
+      "id": "anon-003",
+      "description": "Anonymous request via DIRECT routing with 2-hop path",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "anon_req",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 2,
+          "hashes": ["AA", "BB"]
+        },
+        "payload": {
+          "dest_hash": "CC",
+          "sender_pub_key": "404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F",
+          "cipher_mac": "F4B4",
+          "ciphertext": "908A4FC137435774D0BB603F55A06069"
+        }
+      },
+      "binary": "1E 02 AABB CC 404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F F4B4 908A4FC137435774D0BB603F55A06069",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "416E6F6E526571"
+      },
+      "notes": "Header 0x1E = ANON_REQ(7)+DIRECT(2). Direct-routed anonymous request with 2 path hashes."
+    },
+    {
+      "id": "anon-004",
+      "description": "Anonymous request truncated before ciphertext",
+      "type": "invalid",
+      "binary": "1D 00 AB 404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F F4B4",
+      "expected_error": "too_short",
+      "notes": "Payload is only 35 bytes (dest_hash + pub_key + mac). Missing ciphertext. Minimum is 51 bytes."
+    }
+  ]
+}
@@ -0,0 +1,96 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Control Payload - Basic",
+  "spec_ref": "versions/v0.1.0/12-payload-control.md",
+  "protocol_version": 0,
+  "description": "Tests control payload encoding. Control packets carry raw bytes where the first byte's bit 7 indicates zero-hop-only restriction.",
+  "vectors": [
+    {
+      "id": "ctl-001",
+      "description": "Control packet with multi-hop allowed (bit 7 clear)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "control",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "data": "01 AABBCCDD"
+        }
+      },
+      "binary": "2D 00 01 AABBCCDD",
+      "notes": "control_byte=0x01: bit 7 clear, multi-hop allowed."
+    },
+    {
+      "id": "ctl-002",
+      "description": "Control packet with zero-hop only (bit 7 set)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "control",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "data": "80 AABBCCDD"
+        }
+      },
+      "binary": "2E 00 80 AABBCCDD",
+      "notes": "control_byte=0x80: bit 7 set, zero-hop only. Direct route with path_count=0 = zero-hop."
+    },
+    {
+      "id": "ctl-003",
+      "description": "Minimal control packet (1 byte)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "control",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "data": "00"
+        }
+      },
+      "binary": "2D 00 00"
+    },
+    {
+      "id": "ctl-004",
+      "description": "Control packet with zero-hop restriction and data via direct routing",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "control",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "data": "FF 0102030405"
+        }
+      },
+      "binary": "2E 00 FF 0102030405",
+      "notes": "control_byte=0xFF: bit 7 set (zero-hop), all other bits set."
+    }
+  ]
+}
@@ -0,0 +1,129 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - Basic",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Tests encrypted payload encoding (REQ/RESPONSE/TXT_MSG) with known cryptographic material. Uses shared_secret = 0x000102...1F, AES key = first 16 bytes, HMAC key = full 32 bytes.",
+  "vectors": [
+    {
+      "id": "enc-001",
+      "description": "Encrypted TXT_MSG with 5-byte plaintext 'Hello'",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "09 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "plaintext 'Hello' = 48656C6C6F (5 bytes), zero-padded to 16 for AES-128-ECB. MAC is HMAC-SHA256(shared_secret, ciphertext) truncated to 2 bytes."
+    },
+    {
+      "id": "enc-002",
+      "description": "Encrypted REQUEST with 16-byte plaintext (exact AES block)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "request",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "631C",
+          "ciphertext": "0A940BB5416EF045F1C39458C653EA5A"
+        }
+      },
+      "binary": "01 00 ABCD 631C 0A940BB5416EF045F1C39458C653EA5A",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "000102030405060708090A0B0C0D0E0F"
+      },
+      "notes": "16-byte plaintext fills exactly one AES block. No padding needed."
+    },
+    {
+      "id": "enc-003",
+      "description": "Encrypted RESPONSE with 17-byte plaintext (spans 2 AES blocks)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "response",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "9822",
+          "ciphertext": "0A940BB5416EF045F1C39458C653EA5A299F7C29A3E13AE7F64ECBA062FC7560"
+        }
+      },
+      "binary": "05 00 ABCD 9822 0A940BB5416EF045F1C39458C653EA5A299F7C29A3E13AE7F64ECBA062FC7560",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "000102030405060708090A0B0C0D0E0F10"
+      },
+      "notes": "17-byte plaintext: first 16 bytes in block 1, byte 17 zero-padded in block 2. 32 bytes ciphertext total."
+    },
+    {
+      "id": "enc-004",
+      "description": "Encrypted TXT_MSG with 1-byte plaintext",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "83FB",
+          "ciphertext": "2D4135E80761429386BFE3833C535AA8"
+        }
+      },
+      "binary": "09 00 ABCD 83FB 2D4135E80761429386BFE3833C535AA8",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "42"
+      },
+      "notes": "1-byte plaintext 0x42, zero-padded to 16 bytes."
+    }
+  ]
+}
@@ -0,0 +1,69 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - MAC Verification",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Tests MAC verification: valid MACs must pass, tampered MACs or ciphertext must fail.",
+  "vectors": [
+    {
+      "id": "mac-001",
+      "description": "Valid MAC with known ciphertext",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "09 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      }
+    },
+    {
+      "id": "mac-002",
+      "description": "Tampered MAC (first byte changed)",
+      "type": "invalid",
+      "binary": "09 00 ABCD 00B5 D9FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "MAC changed from EAB5 to 00B5. MACThenDecrypt must return 0."
+    },
+    {
+      "id": "mac-003",
+      "description": "Tampered MAC (second byte changed)",
+      "type": "invalid",
+      "binary": "09 00 ABCD EA00 D9FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "MAC changed from EAB5 to EA00."
+    },
+    {
+      "id": "mac-004",
+      "description": "Tampered ciphertext (first byte changed)",
+      "type": "invalid",
+      "binary": "09 00 ABCD EAB5 00FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "Ciphertext first byte changed from D9 to 00. HMAC over modified ciphertext won't match."
+    },
+    {
+      "id": "mac-005",
+      "description": "Swapped MAC bytes",
+      "type": "invalid",
+      "binary": "09 00 ABCD B5EA D9FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "MAC bytes reversed: B5EA instead of EAB5."
+    }
+  ]
+}
@@ -0,0 +1,99 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - AES Block Padding",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Tests AES-128-ECB zero-padding behavior at block boundaries. Plaintexts of 1, 15, 16, 17, and 32 bytes exercise all padding edge cases.",
+  "vectors": [
+    {
+      "id": "pad-001",
+      "description": "1-byte plaintext: padded with 15 zero bytes",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "83FB",
+          "ciphertext": "2D4135E80761429386BFE3833C535AA8"
+        }
+      },
+      "binary": "09 00 ABCD 83FB 2D4135E80761429386BFE3833C535AA8",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "42"
+      },
+      "notes": "1 byte padded to 16: 42 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00. 1 AES block output."
+    },
+    {
+      "id": "pad-002",
+      "description": "16-byte plaintext: no padding needed (exact block boundary)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "631C",
+          "ciphertext": "0A940BB5416EF045F1C39458C653EA5A"
+        }
+      },
+      "binary": "09 00 ABCD 631C 0A940BB5416EF045F1C39458C653EA5A",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "000102030405060708090A0B0C0D0E0F"
+      },
+      "notes": "Exactly 16 bytes: no padding. 1 AES block output."
+    },
+    {
+      "id": "pad-003",
+      "description": "17-byte plaintext: 1 byte in second block, padded with 15 zeros",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "9822",
+          "ciphertext": "0A940BB5416EF045F1C39458C653EA5A299F7C29A3E13AE7F64ECBA062FC7560"
+        }
+      },
+      "binary": "09 00 ABCD 9822 0A940BB5416EF045F1C39458C653EA5A299F7C29A3E13AE7F64ECBA062FC7560",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "000102030405060708090A0B0C0D0E0F10"
+      },
+      "notes": "17 bytes spans 2 blocks. Block 2 = 10 00 00 ... 00. 32 bytes ciphertext."
+    }
+  ]
+}
@@ -0,0 +1,47 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - Roundtrip Verification",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Roundtrip encrypt-then-MAC verification vectors. Each vector provides full key material enabling implementations to verify: (1) encryption produces the given ciphertext, (2) MAC computation produces the given MAC, (3) MAC verification succeeds, (4) decryption recovers the plaintext.",
+  "vectors": [
+    {
+      "id": "rt-enc-001",
+      "description": "Roundtrip: encrypt 'Hello', verify MAC, decrypt back",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "09 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Verification steps: (1) AES-128-ECB encrypt(key=00..0F, pad('Hello')) -> D9FD...3502. (2) HMAC-SHA256(key=00..1F, ct)[:2] -> EAB5. (3) HMAC verify: recompute and compare. (4) AES-128-ECB decrypt -> 48656C6C6F + 11 zero bytes."
+    },
+    {
+      "id": "rt-enc-002",
+      "description": "Roundtrip with wrong MAC must fail verification",
+      "type": "invalid",
+      "binary": "09 00 ABCD FFFF D9FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "Same ciphertext as rt-enc-001 but MAC replaced with FFFF. MACThenDecrypt must return 0 (failure)."
+    }
+  ]
+}
@@ -0,0 +1,76 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - Extra Edge Cases",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Additional encrypted payload tests: non-FLOOD routes, hash_size>1 paths, 32-byte plaintext, and payload-level invalid cases.",
+  "vectors": [
+    {
+      "id": "enc-extra-001",
+      "description": "Encrypted TXT_MSG via DIRECT routing with 2-byte hash path",
+      "type": "encode_decode",
+      "structured": {
+        "header": { "version": 0, "payload_type": "txt_msg", "route_type": "direct" },
+        "path": { "hash_size": 2, "hash_count": 1, "hashes": ["AABB"] },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "0A 41 AABB ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Header 0x0A = TXT_MSG(2)+DIRECT(2). path_len=0x41 (hash_size=2, count=1). Tests encrypted payload with non-FLOOD routing and multi-byte hash."
+    },
+    {
+      "id": "enc-extra-002",
+      "description": "Encrypted TXT_MSG via TRANSPORT_FLOOD with transport codes",
+      "type": "encode_decode",
+      "structured": {
+        "header": { "version": 0, "payload_type": "txt_msg", "route_type": "transport_flood" },
+        "transport_codes": [1000, 0],
+        "path": { "hash_size": 1, "hash_count": 0, "hashes": [] },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "08 E803 0000 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Header 0x08 = TXT_MSG(2)+TRANSPORT_FLOOD(0). Tests encrypted payload with transport codes."
+    },
+    {
+      "id": "enc-extra-003",
+      "description": "ACK payload too short (3 bytes instead of 4)",
+      "type": "invalid",
+      "binary": "0D 00 EFBEAD",
+      "expected_error": "incomplete_payload",
+      "notes": "ACK requires exactly 4 bytes. Only 3 provided."
+    },
+    {
+      "id": "enc-extra-004",
+      "description": "Payload exceeds MAX_PACKET_PAYLOAD (185 bytes)",
+      "type": "invalid",
+      "binary": "3D 00 000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F606162636465666768696A6B6C6D6E6F707172737475767778797A7B7C7D7E7F808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9FA0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8",
+      "expected_error": "payload_too_large",
+      "notes": "Payload is 185 bytes (0x00..0xB8), exceeding MAX_PACKET_PAYLOAD of 184. readFrom MUST reject."
+    },
+    {
+      "id": "enc-extra-005",
+      "description": "Header 0xFF sentinel on wire (must reject)",
+      "type": "invalid",
+      "binary": "FF 00 DEADBEEF",
+      "expected_error": "sentinel_header",
+      "notes": "Header 0xFF is used internally as do-not-retransmit marker. MUST NOT appear on the wire."
+    }
+  ]
+}
@@ -0,0 +1,38 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Group Data Payload",
+  "spec_ref": "versions/v0.1.0/08-payload-group.md",
+  "protocol_version": 0,
+  "description": "Tests group datagram payload. Same wire format as GRP_TXT but payload type = 0x06.",
+  "vectors": [
+    {
+      "id": "grp-data-001",
+      "description": "Group datagram with known channel secret",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "grp_data",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "channel_hash": "72",
+          "cipher_mac": "D184",
+          "ciphertext": "948C819389BA4ED7B1194A0FF8E62073"
+        }
+      },
+      "binary": "19 00 72 D184 948C819389BA4ED7B1194A0FF8E62073",
+      "crypto_context": {
+        "shared_secret": "202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F",
+        "encryption_key": "202122232425262728292A2B2C2D2E2F",
+        "plaintext": "47726F75704D736721"
+      },
+      "notes": "Header 0x19 = GRP_DATA(6)+FLOOD(1). Same ciphertext as GRP_TXT since same key and plaintext."
+    }
+  ]
+}
@@ -0,0 +1,46 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Group Text Payload",
+  "spec_ref": "versions/v0.1.0/08-payload-group.md",
+  "protocol_version": 0,
+  "description": "Tests group text message payload: channel_hash(1) + cipher_mac(2) + ciphertext.",
+  "vectors": [
+    {
+      "id": "grp-txt-001",
+      "description": "Group text message with known channel secret",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "grp_txt",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "channel_hash": "72",
+          "cipher_mac": "D184",
+          "ciphertext": "948C819389BA4ED7B1194A0FF8E62073"
+        }
+      },
+      "binary": "15 00 72 D184 948C819389BA4ED7B1194A0FF8E62073",
+      "crypto_context": {
+        "shared_secret": "202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F",
+        "encryption_key": "202122232425262728292A2B2C2D2E2F",
+        "plaintext": "47726F75704D736721"
+      },
+      "notes": "Channel hash = SHA256(channel_secret)[0] = 0x72. Plaintext 'GroupMsg!' (9 bytes). AES key = first 16 bytes of channel secret."
+    },
+    {
+      "id": "grp-txt-002",
+      "description": "Group text with tampered MAC must fail",
+      "type": "invalid",
+      "binary": "15 00 72 0000 948C819389BA4ED7B1194A0FF8E62073",
+      "expected_error": "mac_invalid",
+      "notes": "Same ciphertext as grp-txt-001 but MAC zeroed. Verification must fail."
+    }
+  ]
+}
@@ -0,0 +1,108 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Multipart Payload - Basic",
+  "spec_ref": "versions/v0.1.0/11-payload-multipart.md",
+  "protocol_version": 0,
+  "description": "Tests multipart payload encoding: first byte = (remaining << 4) | sub_type. Currently only multipart ACK (sub_type=3) is defined.",
+  "vectors": [
+    {
+      "id": "mp-001",
+      "description": "Multipart ACK with remaining=1, CRC 0xDEADBEEF",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "multipart",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "remaining": 1,
+          "sub_type": 3,
+          "sub_payload": "EFBEADDE"
+        }
+      },
+      "binary": "29 00 13 EFBEADDE",
+      "notes": "First byte: (1<<4)|3 = 0x13. Sub-payload: ACK CRC 0xDEADBEEF as LE."
+    },
+    {
+      "id": "mp-002",
+      "description": "Multipart ACK with remaining=0 (last in sequence)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "multipart",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "remaining": 0,
+          "sub_type": 3,
+          "sub_payload": "01000000"
+        }
+      },
+      "binary": "29 00 03 01000000",
+      "notes": "First byte: (0<<4)|3 = 0x03."
+    },
+    {
+      "id": "mp-003",
+      "description": "Multipart ACK with remaining=15 (maximum)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "multipart",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "remaining": 15,
+          "sub_type": 3,
+          "sub_payload": "FFFFFFFF"
+        }
+      },
+      "binary": "29 00 F3 FFFFFFFF",
+      "notes": "First byte: (15<<4)|3 = 0xF3."
+    },
+    {
+      "id": "mp-004",
+      "description": "Multipart ACK via direct routing",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "multipart",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 2,
+          "hashes": [
+            "AA",
+            "BB"
+          ]
+        },
+        "payload": {
+          "remaining": 2,
+          "sub_type": 3,
+          "sub_payload": "78563412"
+        }
+      },
+      "binary": "2A 02 AABB 23 78563412",
+      "notes": "Header 0x2A = MULTIPART(10)+DIRECT(2). First byte: (2<<4)|3 = 0x23."
+    }
+  ]
+}
@@ -0,0 +1,122 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Path Return Payload - Basic",
+  "spec_ref": "versions/v0.1.0/09-payload-path.md",
+  "protocol_version": 0,
+  "description": "Tests path return payload outer structure: dest_hash(1) + src_hash(1) + encrypt-then-MAC. The encrypted inner format contains path_len + path + extra_type + extra_data.",
+  "vectors": [
+    {
+      "id": "path-001",
+      "description": "Path return with encrypted inner data",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "path",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "21 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Header 0x21 = PATH(8)+FLOOD(1). Same ciphertext as enc-001 since same key/plaintext. The decrypted inner format would be parsed as: path_len=0x48, hash_size=2, hash_count=8 etc. - this is a structural test only."
+    },
+    {
+      "id": "path-002",
+      "description": "Path return via DIRECT routing with 1-hop path",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "path",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 1,
+          "hashes": ["AB"]
+        },
+        "payload": {
+          "dest_hash": "CD",
+          "src_hash": "EF",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "22 01 AB CDEF EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Header 0x22 = PATH(8)+DIRECT(2). Direct-routed path return with 1 hop."
+    },
+    {
+      "id": "path-003",
+      "description": "Path return via TRANSPORT_FLOOD with transport codes",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "path",
+          "route_type": "transport_flood"
+        },
+        "transport_codes": [1, 2],
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "20 0100 0200 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Header 0x20 = PATH(8)+TRANSPORT_FLOOD(0). Transport codes [1, 2] as LE uint16."
+    },
+    {
+      "id": "path-004",
+      "description": "Path return with 2-block ciphertext (32 bytes plaintext)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "path",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "1234",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "21 00 ABCD 1234 D9FD218D50A4409143A7243D6D913502D9FD218D50A4409143A7243D6D913502",
+      "notes": "Path return with 2 AES blocks of ciphertext (32 bytes). Tests multi-block encrypted path data."
+    }
+  ]
+}
@@ -0,0 +1,97 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Raw Custom Payload - Basic",
+  "spec_ref": "versions/v0.1.0/13-payload-raw-custom.md",
+  "protocol_version": 0,
+  "description": "Tests raw custom payload encoding. RAW_CUSTOM carries application-defined raw bytes.",
+  "vectors": [
+    {
+      "id": "raw-001",
+      "description": "Minimal raw custom payload (1 byte)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "raw_custom",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "data": "42"
+        }
+      },
+      "binary": "3E 00 42",
+      "notes": "Header 0x3E = RAW_CUSTOM(15)+DIRECT(2). Single byte payload."
+    },
+    {
+      "id": "raw-002",
+      "description": "Raw custom with binary data",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "raw_custom",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 1,
+          "hashes": [
+            "AA"
+          ]
+        },
+        "payload": {
+          "data": "DEADBEEFCAFEBABE"
+        }
+      },
+      "binary": "3E 01 AA DEADBEEFCAFEBABE",
+      "notes": "Direct route with 1-hop path."
+    },
+    {
+      "id": "raw-003",
+      "description": "Raw custom with all-zero payload",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "raw_custom",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "data": "0000000000000000"
+        }
+      },
+      "binary": "3E 00 0000000000000000"
+    },
+    {
+      "id": "raw-004",
+      "description": "Raw custom with all-FF payload",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "raw_custom",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "data": "FFFFFFFFFFFFFFFF"
+        }
+      },
+      "binary": "3E 00 FFFFFFFFFFFFFFFF"
+    }
+  ]
+}
@@ -0,0 +1,127 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Trace Payload - Basic",
+  "spec_ref": "versions/v0.1.0/10-payload-trace.md",
+  "protocol_version": 0,
+  "description": "Tests the basic 9-byte TRACE payload structure: tag(4) + auth_code(4) + flags(1).",
+  "vectors": [
+    {
+      "id": "trc-001",
+      "description": "Basic trace with tag=1, auth_code=2, flags=0",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "trace",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "tag": 1,
+          "auth_code": 2,
+          "flags": 0
+        }
+      },
+      "binary": "25 00 01000000 02000000 00",
+      "notes": "tag=1 LE=01000000, auth_code=2 LE=02000000, flags=0."
+    },
+    {
+      "id": "trc-002",
+      "description": "Trace with large tag and auth_code values",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "trace",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "tag": 4294967295,
+          "auth_code": 305419896,
+          "flags": 0
+        }
+      },
+      "binary": "25 00 FFFFFFFF 78563412 00",
+      "notes": "tag=0xFFFFFFFF, auth_code=0x12345678 LE=78563412."
+    },
+    {
+      "id": "trc-003",
+      "description": "Trace with flags indicating 1-byte path hash size (flags & 0x03 = 0)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "trace",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "tag": 100,
+          "auth_code": 200,
+          "flags": 0
+        }
+      },
+      "binary": "25 00 64000000 C8000000 00",
+      "notes": "flags=0: path_hash_size = 1 << (0 & 3) = 1 byte."
+    },
+    {
+      "id": "trc-004",
+      "description": "Trace with flags indicating 2-byte path hash size (flags & 0x03 = 1)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "trace",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "tag": 100,
+          "auth_code": 200,
+          "flags": 1
+        }
+      },
+      "binary": "25 00 64000000 C8000000 01",
+      "notes": "flags=1: path_hash_size = 1 << (1 & 3) = 2 bytes."
+    },
+    {
+      "id": "trc-005",
+      "description": "Trace sent via direct routing with path hashes appended to payload",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "trace",
+          "route_type": "direct"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "data": "01000000 02000000 00 AABBCC"
+        }
+      },
+      "binary": "26 00 01000000 02000000 00 AABBCC",
+      "notes": "Header 0x26 = TRACE(9)+DIRECT(2). path_len=0 (path field used for SNR). Payload: 9-byte header + 3 path hash bytes. Using raw payload since the appended hashes are semantically part of the trace."
+    }
+  ]
+}