# BREAKER - Architecture

## Overview

Breaker is a four-layer pipeline: **classify → evidence → stamp → audit**.
It has no executor. It cannot trade, send, or withdraw. It reads market data and stamps.

## Layers

```
┌─────────────────────────────────────────────────────────────┐
│                        USER PASTE                           │
│  "Long BTCUSDT 20x with $200 margin. Copy me."             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 1: CLASSIFIER                                         │
│                                                              │
│  Priority chain - first match wins:                          │
│                                                              │
│    1. SPEND  → buy/send/withdraw intent      → hard TRIP     │
│    2. DATA   → price/range query, no target  → CLEAR         │
│    3. FAKE   → scam patterns, deposit addr   → TRIP          │
│    4. LIQ    → leverage, futures, copy trade  → TRIP         │
│    5. CALL   → hopium, guaranteed, urgency    → TRIP         │
│    6. UNKNOWN → nothing matched               → TRIP (closed)│
│                                                              │
│  Tools: regex pattern banks, keyword extraction,             │
│         leverage parser, pair extractor, address finder       │
└──────────────────────┬──────────────────────────────────────┘
                       │
          evidence needed? (PENDING_MCP)
          ┌────────────┴────────────┐
          │ yes                     │ no
          ▼                         ▼
┌──────────────────────┐   ┌──────────────────────┐
│  LAYER 2: EVIDENCE   │   │  (skip - FAKE/SPEND  │
│                      │   │   have local evidence)│
│  Tier 1: Binance MCP │   └──────────────────────┘
│    spot_ticker24hr   │              │
│    [binance_mcp] tag │              │
│                      │              │
│  Tier 2: Binance REST│              │
│    api.binance.com   │              │
│    /api/v3/ticker    │              │
│                      │              │
│  Tier 3: CoinGecko   │              │
│    FALLBACK label    │              │
│                      │              │
│  All fail: None      │              │
│    → stamp anyway    │              │
└──────────┬───────────┘              │
           │                          │
           └────────────┬─────────────┘
                        ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 3: STAMP FORMATTER                                    │
│                                                              │
│  DOOR: LIQ                                                   │
│  WHY: At 20x, a move of about 5% wipes the margin.          │
│  EVIDENCE: BTCUSDT $79,906 | 24h: -0.03% | 20x | ~5%       │
│            [binance_mcp]                                     │
│  STAMP: BREAKER: TRIP                                        │
│  NEXT: Do not click.                                         │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────┐
│  LAYER 4: AUDIT                                              │
│                                                              │
│  Appends one JSON line to audit.log:                         │
│  {"ts":"…","door":"LIQ","stamp":"BREAKER: TRIP",             │
│   "input_preview":"Long BTCUSDT 20x…"}                      │
│                                                              │
│  Read-only. Never truncated. One line per classification.    │
└──────────────────────────────────────────────────────────────┘
```

## State Machine

```
          ┌───────┐
          │ PASTE │
          └───┬───┘
              │
      ┌───────▼────────┐
      │  is SPEND?     │───yes───▶ TRIP (policy, no evidence)
      └───────┬────────┘
              │ no
      ┌───────▼────────┐
      │  is DATA?      │───yes───▶ fetch MCP ──▶ CLEAR
      └───────┬────────┘
              │ no
      ┌───────▼────────┐
      │  is FAKE?      │───yes───▶ extract address ──▶ TRIP
      └───────┬────────┘
              │ no
      ┌───────▼────────┐
      │  has leverage?  │───yes───▶ wipe math + MCP ──▶ TRIP
      └───────┬────────┘
              │ no
      ┌───────▼────────┐
      │  is CALL?      │───yes───▶ claim vs price ──▶ TRIP
      └───────┬────────┘
              │ no
      ┌───────▼────────┐
      │  UNKNOWN       │─────────▶ fail closed ──▶ TRIP
      └────────────────┘
```

## Fail-Closed Table

| Scenario | Behavior |
|----------|----------|
| MCP down, LIQ paste | TRIP - leverage math is local. Evidence = FALLBACK. |
| MCP down, CALL paste | TRIP - hopium keywords are local. |
| MCP down, FAKE paste | TRIP - scam patterns are local. |
| MCP down, DATA query | CLEAR with `EVIDENCE: FALLBACK`. No price if all tiers fail. |
| MCP down, SPEND request | TRIP - policy gate, no evidence needed. |
| Unrecognized paste | TRIP - fail closed. "Ask a trusted source." |
| Classifier error | TRIP - exception handler defaults to UNKNOWN. |

**No silent failure.** Every paste gets a stamp. MCP is evidence, not permission.

## Evidence Tiers

| Tier | Source | Tag | Latency |
|------|--------|-----|---------|
| 1 | Binance MCP (`agent.binance.com`) | `[binance_mcp]` | ~200ms |
| 2 | Binance REST API (`api.binance.com`) | `[binance_rest]` | ~300ms |
| 3 | CoinGecko (`api.coingecko.com`) | `[coingecko]` | ~500ms |
| - | All fail | `FALLBACK` | 0ms (local rules only) |

DNS is checked once per process. If Binance is unreachable, tier 2 is skipped for all subsequent calls.

## What Is NOT in This Architecture

| Absent | Why |
|--------|-----|
| Trading engine | allow_trades = false |
| Order router | No executor |
| Wallet sender | allow_withdrawals = false |
| Delta-neutral hedger | Not a trading product |
| Prediction market | Not in scope |
| Fourth door | Three doors only |
| Discord bot | Not in scope |
| Dashboard with PnL | Breaker does not track positions |

## Files

| File | Role |
|------|------|
| `src/breaker.py` | Classifier + leverage math + stamp formatter + audit |
| `src/evidence.py` | Three-tier fetcher with DNS caching + fail-closed |
| `prompts/system.md` | System prompt for Claude Code agent mode |
| `mandate.json` | Hardcoded policy (no trades, no withdrawals) |
| `audit.log` | Append-only JSON lines |