Rearchitecture Plan

Annihilation Rearchitecture Plan

This page captures the target architecture for the current rewrite. It is the clearest source of truth for the new stack, vocabulary, data model, supervision tree, and migration path.

Stack Decisions

Layer	Technology	Replaces
Storage	Postgres + Ecto	SQLite + legacy Keeper
Hot state	ETS	AssumptionsLedger, Session.Store
Events	Phoenix.PubSub	Registry PubSub
UI	Phoenix LiveView	ExRatatui TUI
Desktop window	elixir_desktop (wxWebView)	terminal
Config/rules	AGENTS.md + Postgres	YAML files

Vocabulary

Term	Meaning
Quantum	Atomic unit of work
Psychonaut	An LLM agent instance
Annihilation	A group of psychonauts / the system itself
Burst	One orchestration cycle
Wave	Full pass through all quanta
Tether	The human operator
Reaching	Agent question to tether
Drift	Assumption made on question timeout
Grounding	Tether reviewing a drift or code change
Pipeline	Named sequence of stages processing a quantum
Playbook	Learned behavioral rules with confidence scores
Skill	Reusable agent prompt template
Diary	Agent’s in-session decision log

Postgres Schema

-- Core work unit
quanta
  id uuid pk
  title text
  body text
  status text          -- open | running | blocked | done | error
  priority int
  type text
  labels text[]
  pipeline_id uuid fk
  parent_id uuid fk    -- for subtasks spawned by agents
  session_id uuid fk
  created_at timestamptz
  updated_at timestamptz

-- Pipeline definitions (replaces pipelines.yaml)
pipelines
  id uuid pk
  name text unique
  is_default bool
  created_at timestamptz

pipeline_stages
  id uuid pk
  pipeline_id uuid fk
  position int
  role text            -- orchestrator | coder | tester | security | docs
  agent_config jsonb
  fan_out bool

-- Learned behavioral rules (replaces playbook.yaml)
playbook_rules
  id uuid pk
  body text
  confidence float
  maturity text        -- nascent | established | proven
  evidence_count int
  active bool
  created_at timestamptz
  updated_at timestamptz

-- Reusable prompt templates (replaces skills.yaml)
skills
  id uuid pk
  name text unique
  prompt_template text
  alpha float          -- Thompson sampling Beta distribution
  beta float
  created_at timestamptz
  updated_at timestamptz

-- Sessions
sessions
  id uuid pk
  started_at timestamptz
  ended_at timestamptz
  wave_count int
  burst_count int

-- Append-only event log (replaces JSONL session files)
session_events
  id bigserial pk
  session_id uuid fk
  topic text
  payload jsonb
  inserted_at timestamptz

-- Human-agent interaction
assumptions
  id uuid pk
  quantum_id uuid fk
  agent_id text
  question text
  assumption text
  status text          -- pending | grounded | rejected | noted
  created_at timestamptz
  resolved_at timestamptz

Notes:

• Full-text search moves to Postgres over session_events.
• GIN indexes cover payload search; a tsvector can cover topics and selected text fields.

ETS Tables

Table	Contents	Owner
:agent_registry	{agent_id, pid, quantum_id, phase}	Agent.Registry
:file_leases	{path, agent_id, mode, expires_at}	File.LeaseTable
:burst_state	current burst phase + metadata	Burst.Manager
:question_queue	{priority, quantum_id, agent_id, question}	Tether.QuestionQueue

Supervision Tree

Annihilation.Application
├── Annihilation.Repo
├── Annihilation.PubSub
├── AnnihilationWeb.Endpoint
├── Desktop.Window
├── Agent.Registry
├── File.LeaseTable
├── Agent.RecursionSemaphore
├── Agent.DynamicSupervisor
├── Tether.QuestionQueue
├── Burst.Manager
└── Reflection.Scheduler

Project Layout

lib/
  annihilation/
    application.ex
    config.ex
    event.ex

    agent/
      server.ex
      provider.ex
      provider/
        anthropic.ex
        mock.ex
      tools.ex
      tools/
        ask_user.ex
        file_read.ex / file_write.ex
        shell.ex
        recurse.ex / recurse_fan_out.ex
        check_messages.ex
        list_psychonauts.ex
        whois.ex
        set_pipeline.ex / create_pipeline.ex
        search_sessions.ex
        search_skills.ex / create_skill.ex
        read_diary.ex
        propose_playbook_delta.ex
      recursion.ex
      registry.ex

    quanta/
      quantum.ex
      quanta.ex
      migrations/

    burst/
      manager.ex
      collector.ex
      runner.ex

    file/
      lease_table.ex
      leases.ex

    memory/
      playbook.ex
      diary.ex
      confidence.ex

    pipeline/
      pipeline.ex
      pipelines.ex
      grounding.ex

    reflection/
      scheduler.ex
      extractor.ex
      curator.ex

    search/
      sessions.ex

    security/
      command_guard.ex
      trauma_guard.ex

    session/
      sessions.ex
      events.ex

    skills/
      skill.ex
      skills.ex

    tether/
      question_queue.ex
      assumptions.ex
      late_beacon_handler.ex

  annihilation_web/
    endpoint.ex
    router.ex
    live/
      dashboard_live.ex
      focus_live.ex
      tether_live.ex
      grounding_live.ex
      quanta_live.ex
    components/
      agent_card.ex
      streaming_output.ex
      question_modal.ex
      drift_card.ex

mix.exs
config/
  config.exs
  dev.exs
  prod.exs
  test.exs
.annihilation/
  config.toml
AGENTS.md

LiveView Layout

┌─────────────────────────────────────────────────────┐
│  annihilation        [wave 3 · burst 12]   ● live   │
├──────────┬──────────────────────────────────────────┤
│          │                                          │
│  nav     │   main content area (LiveView)           │
│          │                                          │
│ Dashboard│                                          │
│ Quanta   │                                          │
│ Tether ③ │                                          │
│ Grounding│                                          │
│ Focus    │                                          │
│          │                                          │
└──────────┴──────────────────────────────────────────┘

• Dashboard: psychonaut cards, streaming output, activity feed, and burst state machine status
• Quanta: kanban columns for open | running | blocked | done | error
• Tether: pending questions and drift review cards
• Grounding: code diffs and pipeline mutations pending approval
• Focus: full conversation, tool calls, diary entries, and phase timeline for one psychonaut

Startup Flow

# Normal (opens native window via elixir_desktop)
mix annihilation

# Headless (no window, structured log to stdout)
mix annihilation --headless

# Specific project root
mix annihilation --root /path/to/project

mix annihilation should:

1. Load config from ~/.annihilation/config.toml plus project overrides
2. Start the OTP app and supervision tree
3. Run Ecto migrations
4. Seed the default pipeline if none exists
5. Start a new session row in Postgres
6. Open Desktop.Window pointing at http://localhost:4000 unless --headless
7. Leave Burst.Manager in :idle until the tether starts the next wave

Event Topics

Topic	Events
"agent:{id}"	phase_change, delta, tool_call, tool_result, done, error
"agent:lifecycle"	started, done, error
"burst:events"	burst_start, burst_complete, wave_complete
"tether:reaching"	question_created, question_answered, question_timeout
"tether:drifts"	drift_created, drift_grounded, drift_rejected
"quanta:updates"	status_change, created, blocked, unblocked
"system"	session_start, session_end, config_reload

Dependencies

defp deps do
  [
    {:phoenix, "~> 1.7"},
    {:phoenix_live_view, "~> 1.0"},
    {:phoenix_pubsub, "~> 2.0"},
    {:ecto_sql, "~> 3.11"},
    {:postgrex, "~> 0.18"},
    {:desktop, "~> 1.5"},
    {:mint, "~> 1.6"},
    {:castore, "~> 1.0"},
    {:jason, "~> 1.4"},
    {:toml, "~> 0.7"},
    {:stream_data, "~> 1.0", only: [:dev, :test]},
    {:ex_doc, "~> 0.34", only: :dev}
  ]
end

Removed: exqlite, yaml_elixir, ex_ratatui

Migration Plan

1. Add Phoenix and Ecto dependencies, and remove exqlite, yaml_elixir, and ex_ratatui
2. Create Ecto schemas and migrations for the new tables
3. Replace the legacy persistence layer with quanta/ Ecto contexts
4. Replace Registry PubSub with Phoenix.PubSub
5. Replace JSONL session storage with session_events
6. Replace YAML loaders with Ecto seed scripts and AGENTS.md
7. Build LiveView pages one at a time: Dashboard -> Quanta -> Tether -> Grounding -> Focus
8. Wire elixir_desktop once the LiveView surface is stable
9. Delete tui/

AGENTS.md Role

AGENTS.md becomes the human-readable behavioral layer that sits above the learned data stored in Postgres.

# Annihilation — Agent Conventions

- Always run the test suite before marking a quantum done
- Security review is required on any quantum touching auth, payments, or PII
- Prefer small focused quanta over large ones — decompose if > 1 day of work
- Write a diary entry after every tool call explaining your reasoning
- When in doubt, reach (ask the tether) rather than drift

The playbook continues to hold learned rules, confidence scores, and runtime prompt material. AGENTS.md is the stable human layer on top.