SYNTAX Channel — Technical Specification

Version: 1.1 · Status: SPEC · Phase: personal sandbox

1. Architecture

SYNTAX_CHANNEL/
├── BROADCAST/              ← all agents read (alerts, system-wide)
│   └── cursor.<agent>      ← per-agent read-only cursor
├── <AGENT_NAME>/            ← per-agent inbox
│   └── msg_<seq>.json      ← atomic files: temp write → mv
├── ARCHIVE/                 ← processed messages
│   └── <agent>/
│       └── YYYY-MM-DD/
│           └── msg_<seq>.json
├── MANIFEST/                ← per-agent hash-chain
│   └── <agent>.sha256chain
└── BOOTSTRAP.sh             ← cold-start script

Design decisions:

❌ JSONL with concurrent writes → ✅ atomic files (temp write + mv)
❌ Single MANIFEST → ✅ per-agent MANIFEST with hash-chain
❌ Cursor via mv → ✅ read-only cursor in BROADCAST
✅ status: pending|processing|done
✅ Bootstrap-scan at startup for persistent agents

2. Agents

Persistent (inotify-push)

inotifywait on own INBOX. Instant reaction.

Agent	Role
Gateway	External interface (Telegram, etc.)
GUARDIAN	Channel health monitoring
Orchestrator	Task distribution
SPHERE	Long-term memory / context

On-demand (pull-at-start)

Read INBOX at session start, execute, terminate.

Agent	Role
Coder	Code generation
Worker	Compute tasks (fine-tune, etc.)
Executor	Command execution
Human	Decision-making via external interface

3. Message Format

{
  "id": "uuid_v7",
  "seq": 42,
  "from": "agent_name",
  "to": "agent_name | BROADCAST",
  "type": "task | alert | response | heartbeat",
  "status": "pending | processing | done",
  "ref": "sha256_of_related_artifact | null",
  "reply_to": "uuid | null",
  "payload": "text or structured data",
  "chain_prev": "sha256 | null",
  "timestamp": "2026-07-30T12:00:00+03:00",
  "sha256": "hash_of_this_message"
}

Field	Purpose
`status`	`pending` → unread; `processing` → in work; `done` → processed
`seq`	Monotonic per-agent counter
`chain_prev`	SHA256 of agent's previous message — hash chain

4. Atomic Write

CRITICAL: temp file + mv. Never write directly to INBOX.

TEMP=$(mktemp ${SYNTAX_CHANNEL}/${TARGET}/.tmp_msg_XXXXXX)
echo "$JSON" > "$TEMP"
mv "$TEMP" "${SYNTAX_CHANNEL}/${TARGET}/msg_${SEQ}.json"

Guarantees:

mv on same filesystem is atomic in POSIX
Reader sees either nothing or complete file
No broken JSONL lines

5. Bootstrap-scan

Persistent agents on startup (reboot, crash, deploy):

LAST_SEQ=$(tail -1 MANIFEST/GUARDIAN.sha256chain | cut -d' ' -f1)

for msg in INBOX/GUARDIAN/msg_*.json; do
    SEQ=$(echo "$msg" | grep -oP 'msg_\K\d+')
    if [ "$SEQ" -gt "$LAST_SEQ" ]; then
        process "$msg"
    fi
done

6. Per-agent Hash Chain

One file per agent. No contention.

Format: MANIFEST/<agent>.sha256chain

42|550e8400-e29b-41d4-a716-446655440000|a1b2c3...def|2026-07-30T12:00:00+03:00
43|550e8400-e29b-41d4-a716-446655440001|e4f5g6...hij|2026-07-30T12:00:01+03:00

Fields: seq|msg_id|sha256|timestamp

Each message links to SHA256 of previous (chain_prev). GUARDIAN verifies chain integrity every N minutes. Break = alert.

7. Routing

Sender:
  1. Increment own seq
  2. Compute chain_prev = sha256 of previous message
  3. Build JSON
  4. Compute sha256 of entire message
  5. Atomic write to INBOX/<target>/msg_<seq>.json
  6. Append line to MANIFEST/<agent>.sha256chain

Persistent receiver:
  → inotifywait triggers processing
  → status → "processing"
  → after processing: mv to ARCHIVE/<agent>/YYYY-MM-DD/
  → status → "done" (written to archive copy)

On-demand receiver:
  → At startup: read INBOX/<name>/ (all pending)
  → status → "processing" (in-place file update)
  → Process
  → status → "done"
  → mv to ARCHIVE/

8. BROADCAST

BROADCAST is never cleaned by receivers:

Each agent maintains read-only cursor: BROADCAST/cursor.<agent> — last read msg_id
On read: only messages newer than cursor
Cleanup: cron hourly removes messages >24h old, read by ALL active agents
expires_at (optional) for heartbeats — auto-cleanup without cursor check

9. GUARDIAN — Health Monitoring

Verify hash chains of all agents (every 5 minutes)
Detect seq gaps (missed messages)
Monitor INBOX size (alert if >100 pending per agent)
Monitor BROADCAST size (alert if >1000)
Heartbeat monitoring for persistent agents
Alert on anomalies

10. Implementation Priority

#	Component	Depends on
0	Specialist models (ABCD)	—
1	Atomic write + directory structure	—
2	Bootstrap-scan for persistent agents	#1
3	Per-agent MANIFEST + hash chain	#1
4	`status: pending/processing/done`	#1
5	inotifywait daemon (Gateway)	#1–4
6	GUARDIAN monitoring	#5

11. Deferred (v2+)

Unified MANIFEST (replicated from per-agent)
expires_at for heartbeats
GUI dashboard
External agent bridge
Message encryption (currently: secure mesh, not needed)

12. Protocol 0 in Channel Context

SHA256 determinism: every message hashed, chain verifiable
No deletion: mv to ARCHIVE only
Full audit trail: MANIFEST/.sha256chain
GUARDIAN — integrity watchdog

Specification v1.1 · 2026-07-30 · Aelin AquaSoul