ergo-framework

# Ergo Framework

Build distributed, fault-tolerant actor-based systems in Go with Erlang-like reliability. Ergo Framework provides actor model, supervision trees, network transparency, and cluster support.

## When to Use This Skill

- Implementing actors with Ergo Framework
- Designing supervision trees for fault tolerance
- Building distributed systems with cluster support
- Integrating TCP/UDP/HTTP with actor model via meta processes
- Configuring service discovery with etcd or Saturn
- Implementing message patterns (Send, Call, Important Delivery)
- Serializing messages with EDF for cross-node communication

## Core Concepts

### 1. Actor Model

**Process States:**
- ProcessStateInit - initializing, spawning children
- ProcessStateSleep - idle, waiting for messages
- ProcessStateRunning - handling messages
- ProcessStateTerminated - shutting down

**Mailbox Queues (priority order):**
- Urgent (MessagePriorityMax) - processed first
- System (MessagePriorityHigh) - framework messages
- Main (MessagePriorityNormal) - application messages (default)
- Log - logging messages

**Critical Rule:** NEVER use mutexes, goroutines, or blocking operations in actor callbacks.

### 2. Supervision

**Strategies:**
- OneForOne - only failing child restarts (default)
- AllForOne - all children restart
- RestForOne - failed + later siblings restart
- SimpleOneForOne - dynamic worker pool

**Child Restart Policies:**
- Permanent - always restart
- Transient - restart on abnormal termination
- Temporary - never restart

### 3. Message Patterns

**Async (Send):** Fire-and-forget, no response expected
**Sync (Call):** Blocks until response received
**Important Delivery:** Confirms delivery to remote mailbox
**FR-2PC:** Fully-Reliable Two-Phase Commit for distributed transactions

### 4. Application Structure

**ApplicationSpec fields:**
- Name, Description, Version
- Mode (Temporary/Transient/Permanent)
- Group (process members)
- Map (role to process name mapping)
- Tags (blue/green,