clonic

Wire protocol types and codec for the Zone Coordination Protocol (ZCP).

clonic defines the binary envelope format that every ZCP message uses on the wire. It is deliberately minimal: types, constants, encode, decode. No crypto, no transport, no business logic.

Think of it like the http crate: it defines Request and Response but doesn't open sockets. ZluidrOS and ZluidrEdge SDK build actual networking on top.

Why "clonic"?

In neurology, a tonic-clonic seizure involves two phases: sustained contraction (tonic) followed by rapid rhythmic pulses across the nervous system (clonic).

tonic is already the Rust ecosystem's gRPC framework — sustained connections. clonic completes the pair: rapid, rhythmic coordination pulses across a distributed device mesh. The fleet is the nervous system.

Who Uses This

Envelope Layout

Offset  Size  Field              Description
───────────────────────────────────────────────────────
0       1     version            Protocol version (0x01)
1       1     msg_type           Message type discriminant
2       1     crypto_suite       Crypto profile (0x01=PQ, 0x02=classical)
3       1     flags              Bit flags (compressed, fragmented)
4       32    sender_device_id   Ed25519 public key
36      2     residency_tag      ISO 3166-1 numeric, big-endian
38      4     payload_length     Payload byte count, big-endian
────────────────────────────────────────────────────────  42 bytes
42      var   payload            Encrypted (opaque to this crate)
42+N    16    mac                AES-256-GCM authentication tag

All multi-byte integers are big-endian (network byte order).

Usage

no_std — Zero-copy parsing (ESP32, bare-metal)

use clonic::{EnvelopeRef, MsgType};

fn handle_frame(buf: &[u8]) {
    let env = EnvelopeRef::parse(buf).expect("valid envelope");

    match env.msg_type() {
        Some(MsgType::SyncCrdt) => {
            let payload = env.payload();
            let residency = env.residency_tag();
            // hand off to sync engine...
        }
        _ => { /* forward or drop */ }
    }
}

alloc — Owned envelopes (ZluidrOS)

use clonic::{Envelope, MsgType, CryptoSuite, ResidencyTag};

let envelope = Envelope::new(
    MsgType::TaskRoute,
    CryptoSuite::PqHybrid,
    device_public_key,           // [u8; 32]
    ResidencyTag::INDONESIA,
    encrypted_payload,           // Vec<u8>
    gcm_tag,                     // [u8; 16]
);

let wire_bytes = envelope.to_bytes();

Transport framing

use clonic::decode::peek_frame_length;
use clonic::envelope::HEADER_SIZE;

// Step 1: read exactly 42 bytes from the wire
let header_buf = read_exact(stream, HEADER_SIZE);

// Step 2: learn total frame size
let (_, total) = peek_frame_length(&header_buf).unwrap();

// Step 3: read remaining bytes
let mut frame = vec![0u8; total];
frame[..HEADER_SIZE].copy_from_slice(&header_buf);
read_exact(stream, &mut frame[HEADER_SIZE..]);

// Step 4: parse
let env = clonic::EnvelopeRef::parse(&frame).unwrap();

Feature Flags

What This Crate Does NOT Do

• No crypto — consumers bring their own (PQ hybrid or classical). The crate defines where crypto fields sit in the envelope but performs no encryption.
• No transport — no TCP, BLE, LoRa, libp2p. Transport-agnostic by design.
• No CRDT payloads — the payload field is opaque bytes.
• No business logic — no task scheduling, no routing decisions.

Repository Structure

clonic (MIT)            ← you are here
├──▶ zluidros           Full OS (stronger license)
├──▶ zluidros-edge-sdk  Embedded SDK (Apache-2.0)
└──▶ (third parties)    Anyone speaking ZCP

License

MIT — maximum adoption, zero friction. The value capture is upstream in ZluidrOS and the SaaS/data layers, not at the protocol level.

About

Part of the ZluidrOS ecosystem by PT Teknorakit Inovasi Indonesia. ZluidrOS is a purpose-built operating system for distributed, AI-capable computing in resource-constrained, sovereignty-conscious environments.