SPEC.md

# 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

```json
{
  "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.

```bash
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):

```bash
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/<agent>.sha256chain
- GUARDIAN — integrity watchdog

---

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