# Message Passing: Design Comparison

**Purpose**: Compare our design decisions against Beads and Tissue to validate approach and identify gaps.

## Summary Comparison

| Decision | Our Design (v2) | Beads | Tissue |
|----------|-----------------|-------|--------|
| **Primary storage** | SQLite (WAL mode) | SQLite + JSONL export | JSONL (append-only) |
| **Cache/index** | N/A (SQLite is primary) | SQLite is primary | SQLite (derived) |
| **Write locking** | SQLite BEGIN IMMEDIATE | SQLite BEGIN IMMEDIATE | None (git merge) |
| **Concurrency model** | SQLite transactions | Optimistic (hash IDs) + SQLite txn | Optimistic (git merge) |
| **Crash safety** | SQLite atomic commit | SQLite transactions | Git (implicit) |
| **Heartbeats** | Yes (10s interval) | No (daemon only) | No |
| **Liveness detection** | SQL query on heartbeat timestamps | Not documented | Not documented |
| **Large payloads** | Blob storage (>4KB) | Compaction/summarization | Not addressed |
| **Coordination** | Polling + claim-check | `bd ready` queries | `tissue ready` queries |
| **Message schema** | Explicit (id, ts, from, type, payload) | Implicit (issue events) | Implicit (issue events) |
| **Human debugging** | JSONL export (read-only) | JSONL in git | JSONL primary |

**Decision (2026-01-10)**: After orch consensus with 3 models, we aligned with Beads' approach (SQLite primary) over Tissue's (JSONL primary). Key factors:
- Payloads 1-50KB exceed POSIX atomic write guarantees (~4KB)
- Crash mid-write with flock still corrupts log
- SQLite transactions provide true atomicity
- JSONL export preserves human debugging (`tail -f`)

## Detailed Analysis

### Where We Align

**1. JSONL as Source of Truth**
All three systems use append-only JSONL as the authoritative store. This is the right call:
- Git-friendly (merges cleanly)
- Human-readable (debuggable with `cat | jq`)
- Simple to implement

**2. SQLite as Derived Cache**
All three use SQLite for queries, not as primary storage:
- Beads: Always-on cache with dirty tracking
- Tissue: Derived index, gitignored
- Ours: Phase 2 optimization

**3. Pull-Based Coordination**
All use polling/queries rather than push events:
- `bd ready` / `tissue ready` / our `poll()` function
- Simpler than event-driven, works across process boundaries

### Where We Diverge

**1. Write Locking Strategy**

| System | Approach | Trade-off |
|--------|----------|-----------|
| **Ours** | flock on JSONL file | Simple, prevents interleaving, works locally |
| **Beads** | SQLite BEGIN IMMEDIATE | Stronger guarantees, more complex |
| **Tissue** | None (trust git merge) | Simplest, but can corrupt JSONL mid-write |

**Our rationale**: flock is simpler than SQLite transactions and safer than trusting git merge for mid-write crashes. Tissue's approach assumes writes complete atomically, which isn't guaranteed for large JSON lines.

**2. Crash Safety**

| System | Approach |
|--------|----------|
| **Ours** | Write to staging → validate → append under lock → delete staging |
| **Beads** | SQLite transactions (rollback on failure) |
| **Tissue** | Git recovery (implicit) |

**Our rationale**: Staging directory adds explicit crash recovery without SQLite complexity. If agent dies mid-write, staged file is recovered on restart.

**3. Heartbeats / Liveness**

| System | Approach |
|--------|----------|
| **Ours** | Mandatory heartbeats every 10s, timeout detection |
| **Beads** | Background daemon (no explicit heartbeats) |
| **Tissue** | None |

**Our rationale**: LLM API calls can hang indefinitely. Without heartbeats, a stuck agent blocks tasks forever. Beads/Tissue are issue trackers, not real-time coordination systems.

**4. Large Payload Handling**

| System | Approach |
|--------|----------|
| **Ours** | Blob storage with content-addressable hashing |
| **Beads** | Compaction (summarize old tasks) |
| **Tissue** | Not addressed |

**Our rationale**: Code diffs and agent outputs can be large. Blob storage keeps the log scannable. Beads' compaction is for context windows, not payload size.

**5. Message Schema**

| System | Schema Type |
|--------|-------------|
| **Ours** | Explicit message schema (id, ts, from, to, type, payload) |
| **Beads** | Issue-centric (tasks with dependencies, audit trail) |
| **Tissue** | Issue-centric (similar to Beads) |

**Our rationale**: We need general message passing (state changes, heartbeats, claims), not just issue tracking. Beads/Tissue are issue trackers first; we're building coordination primitives.

### Gaps in Our Design (Learned from Beads)

**1. Hash-Based IDs for Merge Safety**
Beads uses hash-based IDs (e.g., `bd-a1b2`) to prevent merge collisions. We should consider this for message IDs if multiple agents might create messages offline and merge later.

**2. Dirty Tracking for Incremental Export**
Beads tracks "dirty" issues for efficient JSONL export. When we add SQLite cache, we should track which messages need re-export rather than full rescans.

**3. File Hash Validation**
Beads stores JSONL file hash to detect external modifications. We could add this to detect corruption or manual edits.

### Gaps in Our Design (Learned from Tissue)

**1. FTS5 Full-Text Search**
Tissue's SQLite cache includes FTS5 for searching issue content. Useful for "find messages mentioning X" queries in Phase 2.

**2. Simpler Concurrency (Maybe)**
Tissue trusts git merge without explicit locking. For single-machine scenarios with small writes, this might be sufficient. We could offer a "simple mode" without flock for low-contention cases.

## Validation Verdict

Our design is **more complex than Tissue but simpler than Beads**, which matches our use case:

- **Tissue**: Issue tracker, optimizes for git collaboration
- **Beads**: Full workflow engine with daemon, RPC, recipes
- **Ours**: Coordination primitives for multi-agent coding

The key additions we make (heartbeats, blob storage, staging directory) are justified by our real-time coordination requirements that issue trackers don't have.

## Recommended Updates to Design

1. **Add hash-based message IDs** - Prevent merge collisions if agents work offline
2. **Add file hash validation** - Detect log corruption on startup
3. **Document "simple mode"** - No flock for single-agent or low-contention scenarios
4. **Plan for FTS5** - Add to Phase 2 SQLite cache design

## References

- Beads source: https://github.com/steveyegge/beads
- Tissue source: https://github.com/evil-mind-evil-sword/tissue
- Our design: docs/design/message-passing-layer.md