docs(protocol): document frame and replication contract

Author: AlisinaDevelo

CHANGELOG.md

@@ -7,6 +7,7 @@ All notable changes to StreamHive are documented here. This project follows [Sem
 ### Added
 
 - **`p2p`**: `PeerSnapshots` exposes connected peer metadata for operational tooling.
+- **Docs**: protocol reference for SHV1 frames, replication messages, limits, and repair behavior.
 
 ### Changed
 

README.md

@@ -164,6 +164,7 @@ flowchart TB
 - [docs/WORKFLOWS.md](docs/WORKFLOWS.md) — local and CI expectations.
 - [docs/GOVERNANCE.md](docs/GOVERNANCE.md) — branch protection and release hygiene.
 - [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) — Docker and Kubernetes sketch.
+- [docs/PROTOCOL.md](docs/PROTOCOL.md) — frame format, replication messages, limits, and repair behavior.
 - [docs/RELEASE.md](docs/RELEASE.md) — release checklist.
 
 ## Contributing

docs/ARCHITECTURE.md

@@ -32,6 +32,8 @@ flowchart TD
 | `internal/version` | Semver string for releases |
 | `.` | CLI: `run`, health HTTP server, replication demo flags |
 
+For the wire-level frame and message contract, see [PROTOCOL.md](PROTOCOL.md).
+
 ### Core interfaces
 
 The seams are interfaces, so storage and peers are swappable without touching the layers

docs/PROTOCOL.md

@@ -0,0 +1,91 @@
+# Protocol Reference
+
+StreamHive carries replication messages inside `SHV1` frames over a connected TCP peer.
+This document describes the current wire contract for operators and library users.
+
+## Frame Format
+
+Each frame has an 8-byte header followed by an opaque payload:
+
+| Field | Size | Encoding | Meaning |
+|-------|------|----------|---------|
+| Magic | 4 bytes | ASCII | Must be `SHV1` |
+| Length | 4 bytes | big-endian uint32 | Payload length in bytes |
+| Payload | `Length` bytes | protocol-specific | Replication messages are JSON |
+
+`p2p.ReadFrame` and `p2p.WriteFrame` default to `p2p.DefaultMaxFrameBytes`, currently
+`4 << 20` bytes. A frame with a bad magic value fails with `p2p.ErrBadMagic`. A frame
+whose declared payload length exceeds the configured maximum fails with
+`p2p.ErrFrameTooLarge`.
+
+## Replication Payloads
+
+Replication payloads are JSON values decoded into `replication.Message`:
+
+```json
+{
+  "type": "blob.put",
+  "key": "base64-encoded-by-json",
+  "data": "base64-encoded-by-json"
+}
+```
+
+The Go `encoding/json` package encodes `[]byte` fields as base64 strings. This applies
+to `key`, `keys`, and `data` fields on the wire.
+
+## Message Types
+
+| Type | Fields | Meaning |
+|------|--------|---------|
+| `blob.put` | `key`, `data` | Store or replace one blob under `key`. |
+| `blob.has` | `keys` | Advertise keys available on the sender. |
+| `blob.missing` | `keys` | Ask the peer to send keys missing locally. |
+| `blob.get` | `key` | Ask the peer to send one key. |
+
+The CLI replication handler uses `blob.has` and `blob.missing` for anti-entropy:
+
+1. A peer advertises local keys on connect.
+2. When `-sync-interval` is set, a peer advertises local keys periodically.
+3. A receiver computes which advertised keys it lacks and sends `blob.missing`.
+4. The owner answers with `blob.put` for keys it can still read.
+
+## Limits
+
+Default replication limits are:
+
+| Limit | Value | Error |
+|-------|-------|-------|
+| Max key size | 512 bytes | `replication.ErrKeyTooLarge` |
+| Max keys per inventory message | 4096 | `replication.ErrTooManyKeys` |
+| Max blob payload | `4 << 20` bytes | `replication.ErrDataTooLarge` |
+
+Empty keys fail with `replication.ErrKeyEmpty`. Empty `keys` lists fail with
+`replication.ErrKeysEmpty`. Unknown message types fail with
+`replication.ErrUnknownMessageType`.
+
+## Content Addressing
+
+`-put-content-key` stores a blob under `SHA-256(data)`. The CLI logs SHA-256 keys as
+hex for readability. On receive, any 32-byte key is treated as a SHA-256 content key
+and verified against the payload before storage. A mismatch fails with
+`storage.ErrSHA256Mismatch` and the blob is not stored.
+
+Opaque caller-chosen keys are still allowed. If an opaque key receives different data,
+the existing value is replaced. If an exact key/data pair is received again, the write is
+skipped and duplicate counters are incremented.
+
+## Failure Behavior
+
+Frame decode errors, message validation errors, storage errors, and peer write errors
+stop the current peer loop. The transport unregisters the peer and updates metrics.
+
+There is no per-key acknowledgement protocol yet. Repair is driven by startup inventory,
+periodic inventory with `-sync-interval`, and reconnect behavior for static `-peers`
+when `-peer-reconnect` is enabled. If a blob send fails mid-sync, a later inventory pass
+or reconnect can request the missing key again.
+
+## Observability
+
+Use `/metrics` for JSON counters, `/metrics/prometheus` for Prometheus text format, and
+`/peers` for connected peer metadata. `/peers` includes remote address, local address,
+direction, connection timestamp, and connection age in milliseconds.