docs(core): split wire vs local constants

tines-core/src/consts.rs

@@ -2,71 +2,84 @@
 //!
 //! Every value here is a compile-time `const` so it can drive generic
 //! parameters (e.g. `heapless::Vec` capacities) and be optimized away.
+//!
+//! They split into two groups (§5): **wire** constants, frozen for wire v1 —
+//! changing any is a `WIRE_VERSION` bump because it changes how a v1 peer
+//! decodes or interprets a frame — and **local** constants, which never cross
+//! the wire and can change in a minor release. Each const is tagged `wire` or
+//! `local`. The private `MAX_FRAGMENTS` in `crate::frag` is also a wire
+//! constant; see its note there.
 
-/// Wire envelope version byte prepended to every serialized `Frame`.
+// ---------------------------------------------------------------------------
-///
+// Wire constants — frozen for wire v1 (any change is a `WIRE_VERSION` bump)
-/// The first byte of every frame on the wire; `crate::wire::Frame::decode`
+// ---------------------------------------------------------------------------
-/// rejects any frame whose leading byte differs from this
+
-/// (`WireError::VersionMismatch`), and [`crate::wire::frame_sender`] skips it.
+/// WIRE. The first byte of every frame on the wire; changing it is a
-/// `4` is the first value in the `4..=0x7F` range that fits a single-byte
+/// `WIRE_VERSION` bump. `crate::wire::Frame::decode` rejects a leading byte
-/// postcard enum tag and sits above the 0.x tag values (`0..=3`).
+/// that differs (`WireError::VersionMismatch`), and [`crate::wire::frame_sender`]
+/// emits this. `4` is the first value in the `4..=0x7F` range that fits a
+/// single-byte postcard enum tag and sits above the 0.x tag values (`0..=3`).
 pub const WIRE_VERSION: u8 = 4;
 
-/// Maximum topic length in bytes.
+/// WIRE. Decoder capacity bound: a peer rejects any topic longer than this.
 pub const MAX_TOPIC: usize = 64;
 
-/// Maximum payload length in bytes.
+/// WIRE. Decoder capacity bound: a peer rejects any payload longer than this.
 pub const MAX_PAYLOAD: usize = 1024;
 
-/// Maximum signature length in bytes. The 1.0 signature slot reserves this on
+/// WIRE. Both sides must agree; this signature slot is reserved on every
-/// every observation (`[crate::observation::Signature]`); it is carried verbatim
+/// observation (`[crate::observation::Signature]`) and carried verbatim,
-/// and never signed or verified until 1.1.
+/// never signed or verified until 1.1. `64` fits Ed25519.
 pub const MAX_SIG: usize = 64;
 
-/// Maximum number of peers a node tracks.
+/// WIRE. Per-key summary capacity a peer expects when decoding a summary.
-pub const MAX_PEERS: usize = 8;
-
-/// Maximum size, in bytes, of a per-key summary.
 pub const SUMMARY_BYTES: usize = 512;
 
-/// Number of hash functions used by the per-key Bloom filter.
+/// WIRE. Both sides must agree on the number of hash functions to read a
+/// Bloom filter in a summary.
 pub const BLOOM_K: usize = 3;
 
-/// Interval, in milliseconds, between summary emissions.
+/// WIRE. Decoder capacity bound (`Frag.data` is an inline `Vec<u8, MAX_FRAME>`),
-pub const SUMMARY_INTERVAL_MS: u64 = 2000;
+/// so a peer cannot decode a bigger frame; a known 2.0 trigger (R3).
-
-/// Timeout, in milliseconds, for inbound frame reassembly.
-pub const REASSEMBLY_TIMEOUT_MS: u64 = 5000;
-
-/// Maximum number of frames buffered for outbound delivery.
-pub const SEND_QUEUE_CAP: usize = 256;
-
-/// Minimum usable UDP frame size in bytes (the BLE floor below which a
-/// fragment header leaves no room for payload). `crate::frag::fragment` gives
-/// up cleanly with `WireError::TooLarge` for any `mtu` below this rather than
-/// emitting a truncated frame; the MTU sweep runs from here to [`MAX_FRAME`].
-pub const MIN_MTU: usize = 23;
-
-/// Maximum UDP frame size in bytes.
 pub const MAX_FRAME: usize = 1500;
 
-/// Maximum number of content-IDs an `Ack` receipt may carry.
+/// WIRE. Decoder capacity bound on an `Ack` receipt's content-ID list.
 pub const ACK_IDS_CAP: usize = 90;
 
-/// Cap on the `Exchange` `events` queue of `NodeEvent`s (one per broadcast id
+// ---------------------------------------------------------------------------
-/// a peer has confirmed).
+// Local constants — never cross the wire (safe to change in a minor release)
+// ---------------------------------------------------------------------------
+
+/// LOCAL. Node-local peer table; never sent on the wire.
+pub const MAX_PEERS: usize = 8;
+
+/// LOCAL. Emission cadence; local scheduling only.
+pub const SUMMARY_INTERVAL_MS: u64 = 2000;
+
+/// LOCAL. Inbound reassembly timer; local only.
+pub const REASSEMBLY_TIMEOUT_MS: u64 = 5000;
+
+/// LOCAL. Outbound delivery buffer size; local only.
+pub const SEND_QUEUE_CAP: usize = 256;
+
+/// LOCAL. BLE floor / MTU-sweep lower bound: below this a fragment header
+/// leaves no room for payload. Used by the frag sweep
+/// (`crate::frag`) and the BLE transport clamp; never carried on the wire.
+pub const MIN_MTU: usize = 23;
+
+/// LOCAL. In-node `Exchange` `events` queue of `NodeEvent`s; never leaves the
+/// node (unlike the wire `ACK_IDS_CAP`).
 pub const EVENT_QUEUE_CAP: usize = 64;
 
-/// Cap on the `Exchange` counted-drop table of distinct `(addr, DropReason)`
+/// LOCAL. `Exchange` counted-drop table of distinct `(addr, DropReason)`
 /// pairs. Once full, further counted drops fold into a single overflow counter
 /// (reported with no address); see [`crate::exchange::NodeEvent::Dropped`].
 pub const DROP_TABLE_CAP: usize = 32;
 
-/// Cap on the `Exchange` per-peer `bcast_sent` table of broadcast ids
+/// LOCAL. `Exchange` per-peer `bcast_sent` table of broadcast ids dispatched
-/// dispatched to a peer.
+/// to a peer.
 pub const BCAST_SENT_CAP: usize = 256;
 
-/// Cap on the number of pending ack ids (`acks` for addressed, `bcast_acks`
+/// LOCAL. Pending ack-id buffer (`acks` for addressed, `bcast_acks` for
-/// for broadcast) buffered before the next Ack is emitted. Overflow drops
+/// broadcast) before the next Ack is emitted; overflow drops the oldest entry.
-/// the oldest pending entry.
 pub const ACK_BUFFER_CAP: usize = 256;

tines-core/src/frag.rs

@@ -12,6 +12,9 @@ pub(crate) const FRAG_OVERHEAD: usize = 65;
 
 /// The most fragments one observation may be split into: the reassembler
 /// tracks received indices in a `u64` bitset.
+///
+/// WIRE. Frozen for wire v1 — changing it changes how a v1 peer reassembles a
+/// fragmented observation.
 pub(crate) const MAX_FRAGMENTS: usize = 64;
 
 /// Splits an encoded observation of `len` bytes for a link of `mtu` bytes,