Architecture

watercooler/threads    # Orphan branch, no common history with code branches
└── threads/
    └── feature-auth.md

~/.watercooler/worktrees/<repo-hash>/
├── graph/
│   └── baseline/
│       ├── manifest.json
│       └── threads/
│           ├── feature-auth/
│           │   ├── meta.json
│           │   ├── entries.jsonl
│           │   └── edges.jsonl
│           └── bug-cors/
│               ├── meta.json
│               ├── entries.jsonl
│               └── edges.jsonl
└── watercooler/
    └── threads/
        ├── feature-auth.md
        └── bug-cors.md

{
  "id": "thread:feature-auth",
  "type": "thread",
  "topic": "feature-auth",
  "title": "feature-auth — Thread",
  "status": "OPEN",
  "ball": "Claude (alice)",
  "last_updated": "2025-11-05T01:42:12Z",
  "summary": "OAuth implementation planning and review",
  "entry_count": 5
}

{"id":"entry:01HKJM2NQR8XVZWF9PQRS3T4AB","type":"entry","entry_id":"01HKJM2NQR8XVZWF9PQRS3T4AB","thread_topic":"feature-auth","index":0,"agent":"Claude (alice)","role":"planner","entry_type":"Plan","title":"OAuth design","timestamp":"2025-11-05T01:42:12Z","body":"Proposal for OAuth flow...","summary":"OAuth architecture proposal","file_refs":["src/auth/oauth.py"],"pr_refs":[],"commit_refs":[]}
{"id":"entry:01HKJM2NQR8XVZWF9PQRS3T4AC","type":"entry","entry_id":"01HKJM2NQR8XVZWF9PQRS3T4AC","thread_topic":"feature-auth","index":1,"agent":"Codex (alice)","role":"implementer","entry_type":"Note","title":"Implementation","timestamp":"2025-11-05T02:15:33Z","body":"Implemented OAuth...","summary":"OAuth implementation complete","file_refs":["src/auth/oauth.py","tests/test_oauth.py"],"pr_refs":[123],"commit_refs":["a1b2c3d"]}

{"source":"thread:feature-auth","target":"entry:01HKJM2NQR8XVZWF9PQRS3T4AB","type":"contains"}
{"source":"thread:feature-auth","target":"entry:01HKJM2NQR8XVZWF9PQRS3T4AC","type":"contains"}
{"source":"entry:01HKJM2NQR8XVZWF9PQRS3T4AB","target":"entry:01HKJM2NQR8XVZWF9PQRS3T4AC","type":"followed_by"}

from watercooler.commands_graph import say, ack, handoff, set_status, set_ball

# Main entry point for write operations
def say(topic, threads_dir, agent, role, title, body, ...):
    """Post entry and flip ball to counterpart."""
    # 1. Determine ball target
    # 2. Call append_entry with ball parameter
    # 3. Return thread path

def append_entry(topic, threads_dir, agent, role, title, entry_type, body, ball, ...):
    """Append structured entry to graph."""
    # 1. Ensure thread exists
    # 2. Get next entry index
    # 3. Upsert entry node
    # 4. Update thread metadata
    # 5. Project to markdown

from watercooler.baseline_graph.writer import (
    upsert_thread_node,
    upsert_entry_node,
    update_thread_metadata,
)

def upsert_entry_node(threads_dir, data, prev_entry_id):
    """Create or update an entry node with edges."""
    # 1. Load per-thread data
    # 2. Create entry node
    # 3. Update thread metadata
    # 4. Create edges (contains, followed_by)
    # 5. Write atomically

from watercooler.baseline_graph.reader import (
    list_threads_from_graph,
    read_thread_from_graph,
    get_entry_from_graph,
)

def read_thread_from_graph(threads_dir, topic, code_branch):
    """Read thread with all entries from graph."""
    # 1. Load meta.json
    # 2. Load entries.jsonl
    # 3. Apply code_branch filter
    # 4. Sort by index
    # 5. Return (thread, entries)

from watercooler.baseline_graph.projector import (
    project_and_write_thread,
    create_thread_file,
)

def project_and_write_thread(threads_dir, topic):
    """Reconstruct .md from graph (single source of truth)."""
    # 1. Read graph data
    # 2. Format as markdown
    # 3. Write atomically

from watercooler.agents import (
    _canonical_agent,
    _counterpart_of,
    _default_agent_and_role,
)

def _canonical_agent(agent, registry, user_tag):
    """Return canonical agent name with user tag."""
    # 1. Parse agent and tag
    # 2. Normalize to canonical form
    # 3. Attach user tag (explicit > string > context > OS)

def _counterpart_of(agent, registry):
    """Return the counterpart agent after resolving chains."""
    # 1. Get canonical base
    # 2. Look up in counterpart map
    # 3. Preserve user tag

def generate_summary(entry_body: str, model: str = "qwen2.5:1.5b") -> str:
    """Generate concise summary via llama-server."""
    # 1. Start llama-server with model
    # 2. Send prompt with entry body
    # 3. Extract summary from response
    # 4. Clean and return

def generate_embedding(text: str, model: str = "bge-m3") -> list[float]:
    """Generate embedding vector via llama.cpp."""
    # 1. Ensure model downloaded
    # 2. Run llama.cpp with --embedding flag
    # 3. Parse output vector
    # 4. Return normalized embedding

# Immediate: Structural write + projection
await upsert_entry_node(...)  # ~10ms
await project_and_write_thread(...)  # ~50ms

# Async queue: Git commit + push
enqueue_git_sync()  # Returns immediately

# Background worker commits and pushes
# Can batch multiple operations

from watercooler.lock import AdvisoryLock

lp = lock_path_for_topic(topic, threads_dir)
with AdvisoryLock(lp, timeout=2, ttl=10, force_break=False):
    # Atomic operations on thread
    upsert_entry_node(...)
    update_thread_metadata(...)
    project_and_write_thread(...)