Introduction

Annihilation is being rearchitected into a BEAM-native psychonaut orchestration system with a Phoenix LiveView control room, Postgres as the durable spine, and ETS for hot runtime state.

The operator is still the Tether: the thread back to base reality. Psychonauts still fan out in parallel. Bursts and waves still drive orchestration. But the runtime is moving from a terminal-first prototype toward a persistent system with explicit data models, event streams, and grounding flows.

This introduction tracks the target architecture. Some deeper pages still describe legacy SQLite and terminal-era components while the migration is in progress.

Design Principles

• Durable state belongs in Postgres. Quanta, pipelines, sessions, skills, playbook rules, assumptions, and append-only events live in Ecto-backed tables.
• Hot runtime state belongs in ETS. Agent registry, file leases, burst metadata, and question queue state stay fast in memory under owner processes.
• The operator surface is LiveView. Dashboard, tether, grounding, focus, and quanta views stream live state instead of trapping it inside a terminal session.
• PubSub is explicit infrastructure. Phoenix.PubSub replaces the ad hoc event layer and becomes the backbone for lifecycle, burst, tether, and quantum updates.
• Human control stays real. Reaching, drift, and grounding remain first-class flows. Psychonaut autonomy is useful only if the tether can intervene cleanly.
• Configuration becomes plainer. Human conventions live in AGENTS.md; learned rules and prompt templates move into Postgres where they can be scored and queried.
• Reflection stays central. Session events, diary entries, playbook deltas, and skill scoring still turn completed work into better future behavior.

Key Concepts

Concept	Description
Quantum	The atomic unit of work. Quanta carry status, priority, labels, pipeline association, parentage, and session membership.
Psychonaut	A GenServer-backed LLM agent instance executing a stage in a pipeline.
Burst	One orchestration cycle in which collected quanta are advanced through the current runtime state.
Wave	A full pass through all eligible quanta. Multiple bursts may happen before a wave completes.
Tether	The human operator who answers reachings, grounds changes, and keeps the system connected to real intent.
Reaching	A psychonaut question to the tether.
Drift	An assumption recorded when a reaching times out before the tether responds.
Grounding	The tether’s review of a drift, code change, or pipeline mutation before it becomes accepted system state.
Pipeline	A named ordered sequence of stages that process a quantum. Each stage defines a role, config, and fan-out behavior.
Playbook	Learned behavioral rules with confidence scores and maturity states.
Skill	A reusable prompt template tracked with Thompson-sampling style alpha/beta scores.
Diary	A psychonaut’s in-session decision log, persisted as part of the event stream and reflection pipeline.

System Architecture at a Glance

Annihilation.Application
|
+-- Annihilation.Repo
+-- Annihilation.PubSub
+-- AnnihilationWeb.Endpoint
+-- Desktop.Window
+-- Agent.Registry
+-- File.LeaseTable
+-- Agent.RecursionSemaphore
+-- Agent.DynamicSupervisor
+-- Tether.QuestionQueue
+-- Burst.Manager
+-- Reflection.Scheduler

What Makes It Different

Unlike Python-first orchestration frameworks or toy chat shells, the rearchitected Annihilation is opinionated about where state lives and how humans stay in control:

• Uses the BEAM’s process model and OTP supervision tree instead of thread orchestration or framework glue
• Treats Postgres as a real application spine rather than an afterthought log sink
• Streams live operator state through Phoenix LiveView instead of a closed terminal interface
• Makes tether, reaching, drift, and grounding explicit workflows instead of prompt-level folklore
• Keeps fast-changing process metadata in ETS where it belongs
• Persists sessions as queryable event streams that can drive reflection, search, and evidence-backed rules
• Keeps self-extension, but routes it through human approval boundaries instead of pretending generated changes are safe by default

For the full target model, see Rearchitecture Plan.