feat: add archive client foundation

tests/test_protocol_and_probes.py

@@ -0,0 +1,33 @@
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from archive_clients.probes import probe_root
+from archive_clients.protocol import ProtocolError, decode, encode, new_envelope
+
+
+class ProtocolAndProbeTests(unittest.TestCase):
+    def test_protocol_round_trip_and_duplicate_key_rejection(self):
+        envelope = new_envelope()
+        envelope.heartbeat.sequence = 1
+        self.assertEqual(decode(encode(envelope)).heartbeat.sequence, 1)
+        raw = json.loads(encode(envelope))
+        duplicate = json.dumps(raw).replace("{", '{"messageId":"duplicate",', 1)
+        with self.assertRaises(ProtocolError):
+            decode(duplicate)
+        raw["messageId"] = "not-a-uuid"
+        with self.assertRaisesRegex(ProtocolError, "canonical UUID"):
+            decode(json.dumps(raw))
+
+    def test_filesystem_probe_cleans_up(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            result = probe_root(root)
+            self.assertTrue(result.readable)
+            self.assertTrue(result.writable)
+            self.assertEqual(list(root.iterdir()), [])
+
+
+if __name__ == "__main__":
+    unittest.main()