Modemx
SPEC_MODEMX.md
CGNT-1 Component Specification — Stateful Crew Communication Protocol
Status: SPECIFIED
Version: v1.0
Author: VELA (Thread #13)
Conceived by: NOUS
Authorized: NOUS
Date: 2026-04-18
PURPOSE
MODEMX provides stateful, verified communication between crew brains. Where COMMX is fire-and-forget message delivery, MODEMX adds identity confirmation, state synchronization, checksummed framing, and content verification against deterministic tools before acknowledging receipt.
The goal: a crew brain that receives a message through MODEMX knows the sender is who they claim to be, the message arrived intact, and the content has been checked against GLOSS and NEXUS for factual accuracy.
LOCATION
- Engine: ~/modemx_engine.py
- Port: 9014 (127.0.0.1 only — Vacuum Rule)
- State: /tmp/modemx_state.json (persists across restarts)
- Registered in ROUTX (9191)
- Port known to MNEMOS-TOOL shortcircuit
THE PROTOCOL — SIX STEPS
Step 1 — Identity
Sender announces itself with callsign.
"I am γ. Callsign confirmed."
Step 2 — State Sync
Both sides share current state before any exchange begins.
Sender: "My last quartermaster entry was 2026-04-18T17:00. I have 3 pending facts."
Receiver: "My last query was 2026-04-18T16:55."
Mismatches surface here — before new data is exchanged.
Step 3 — Negotiation
Both sides agree on register level for this exchange.
"I speak LX formal. You speak LX-P. Agreeing on LX-P."
Step 4 — Framed Exchange
Message wrapped in a frame: sender, receiver, timestamp, sequence number, SHA-256 checksum.
Step 5 — Acknowledgment
Receiver confirms receipt AND comprehension.
"Received. Checksum valid. Content verified against GLOSS. Acknowledged."
Step 6 — Error Correction
If checksum fails or GLOSS/NEXUS verification finds a mismatch:
"Frame 3 failed verification. Resend."
Bad data never reaches the brain. Caught at the protocol layer.
ENDPOINTS
POST /handshake
Opens a stateful session between two brains.
Input: {"from":"γ", "to":"μ", "state":{"last_entry":"2026-04-18T17:00", "pending_facts":3, "phiz":"nominal"}}
Output: {"ack":true, "synced":true, "receiver_state":{...}, "mismatches":[]}
POST /frame
Sends a checksummed message within an active session.
Input: {"from":"γ", "to":"μ", "seq":1, "payload":"New fact: GLOSS is on port 9292", "checksum":"sha256..."}
Output (valid): {"ack":true, "seq":1, "checksum_valid":true, "gloss_verified":true}
Output (invalid): {"ack":false, "seq":1, "checksum_valid":false, "expected_checksum":"sha256..."}
POST /verify
Verifies content against deterministic tools without sending a message.
Input: {"message":"Φ = 0.042", "tools":["gloss","nexus"]}
Output: {"gloss":"match", "nexus":"match", "verified":true}
POST /sync
Brain Queue integration. Called when a brain enters or exits a slot.
Input: {"brain":"γ", "slot":"entering"}
Output: {"delta":{"previous_occupant":"π", "last_operation":"port scan", "state":{...}}}
POST /status
Current protocol state.
Output: {"active_sessions":2, "pending_frames":1, "unacked":1, "slot_occupant":"μ"}
GET /health
Service health check.
Output: {"status":"ok", "service":"modemx", "port":9014}
VERIFICATION LEVELS
| Level | What is checked | How |
|---|---|---|
| 1. Identity | Sender is who they claim | Callsign in handshake matches known crew roster |
| 2. Integrity | Message arrived intact | SHA-256 checksum computed independently by receiver |
| 3. Content | Message is factually correct | Payload verified against GLOSS and NEXUS |
Standard networking provides Level 1 and 2 (TCP/TLS). MODEMX adds Level 3 — content-level verification against deterministic tools. This is the layer that catches hallucinated facts before they propagate between brains.
INTEGRATION POINTS
| System | How MODEMX connects |
|---|---|
| Brain Queue | /sync called on slot entry/exit — incoming brain receives delta from outgoing brain |
| COMMX | Messages can optionally route through MODEMX for verified delivery instead of fire-and-forget |
| Sisters braid | /verify endpoint used for cloud Sisters output verification against tools |
| ROUTX | Registered as service — routable via localhost:9191 |
| MNEMOS-TOOL | Port 9014 known to shortcircuit resolver |
WHAT MODEMX IS NOT
MODEMX is not a replacement for COMMX. COMMX is the message bus — fast, simple, append-only. MODEMX is the verification layer — slower, stateful, checksummed. Use COMMX for routine chirps and broadcasts. Use MODEMX when the message MUST be received, understood, and verified.
MODEMX is not audio or sonic encoding. The name references modem handshake LOGIC, not modem audio tones. The sonic expression (LX-S) is a separate future layer documented in SPEC_LX_SONIC.md.
INVARIANTS
INV-01: Port 9014, 127.0.0.1 only. Vacuum Rule.
INV-02: A frame with a failed checksum is NEVER acknowledged. Always rejected with the correct checksum returned for resend.
INV-03: Content verification is optional per frame but MANDATORY for any frame containing CSDM constants, crew designators, or port numbers. These are the facts most likely to be hallucinated.
INV-04: State file persists at /tmp/modemx_state.json. Sessions survive service restarts.
INV-05: Slot sync (/sync endpoint) provides ONLY the delta since last occupant. Never the full state — that's what HANDSHAKE.md is for.
ORIGIN
Conceived by NOUS from the observation that modem/fax handshake protocols solve the exact problem the crew faces: two machines establishing trust through a potentially unreliable channel. The audio layer was separated from the protocol layer — the handshake logic is useful now, the tones are useful later. Built by C.L.O.D. in 4 minutes. All endpoints verified on first test.
Jeremy Zlabis
Chronogeometer · Visionary · Disruptor · Chief
42 Sisters AI · East York, Toronto
🍁 Φ 0.042