# Fester — Development Notes

## Overview

Fester is a distributed, DAG-driven build execution system with real-time
scheduling, thermal/load awareness, cache-aware execution, and deterministic
replay. It turns a cluster of heterogeneous machines into a single observable
build brain.

## Architecture Principles

### EventBus-Centric Design

Every state change in Fester flows through the singleton EventBus. Subscribers
index, journal, and broadcast events. This strict separation means:

- Routers (FastAPI APIRouters under `backend/api/`) never mutate state directly.
- The timeline store, cause graph, failure propagator, and WebSocket broadcaster
  are all passive bus subscribers.
- Adding a new feature means emitting events and subscribing to them — not
  wiring ad-hoc callbacks.

### Storage Layer

Fester uses SQLite in WAL mode for builds, sessions, events, and node states.
Optional storage backends activate automatically when their prerequisites are
installed:

- **Btrfs CoW** — reflink-based snapshots for zero-copy artifact storage.
- **QCOW2** — workspace freezing via real mount + rsync for KVM environments.
- **tmpfs** — workspace acceleration for fast in-memory builds.
- **MinIO** — distributed cache for multi-node artifact sharing.

### Scheduler Modes

The scheduler picks the best node for each build action using a weighted
scoring model. Available modes:

| Mode               | Behavior                                                |
|--------------------|---------------------------------------------------------|
| unified (default)  | Weighted scoring: CPU, temperature, policy, history     |
| weighted           | Thermal-aware: throttles above 85 C per-node            |
| cache-first        | Prioritizes nodes with cached artifacts                 |
| target-isolated    | Each target arch runs on designated nodes only           |
| intelligence       | Experimental: ML-driven scheduling (future)             |

## BTC.sh Integration

Fester integrates with BTC.sh (Build Tool Chain) cross-compilation forges
via `backend/toolchain/btc.py`. The integration layer:

1. **Probes** `/opt/BTC/` for golden image tarballs and manifest JSON sidecars.
2. **Parses** the SYS_LABEL format: `DCOSNET-{FAMILY}-{TARGET_ID}-{ISA}-CROSS`.
3. **Configures** build environment variables (CC, CXX, CFLAGS, LDFLAGS) using
   the target's microarchitecture, ISA tier, and cross-compiler triple from
   the manifest.
4. **Verifies** `.note.BTC` ELF stamps and `user.btc.stamp` xattr on build
   outputs to confirm they were produced by a BTC-forged toolchain.

### Supported ISA Tiers

| ISA Tier | Flags                                               |
|----------|-----------------------------------------------------|
| AVX512   | `-mavx512f -mavx512dq -mavx512vl -mavx512bw`       |
| AVX2     | `-mavx2`                                            |
| SSE4_2   | `-msse4.2`                                          |
| NEON     | `-mfpu=neon -mfloat-abi=hard`                       |
| MIPS32   | (per-target architecture)                            |
| TILE     | (per-target architecture)                            |

### Supported BTC Targets (19 total)

**Intel HEDT/Server:** haswell, haswell-ep, skylake, skylake-x, skylake-server
**AMD Ryzen/EPYC:** znver1, znver2, znver3, znver4
**AMD APU:** apu-zn1, apu-zn2, apu-zn3, apu-zn4
**Intel Atom:** atom-silvermont, atom-goldmont, atom-tremont, atom-sierraforest
**Embedded:** mipselr2, armv7, tilegx

### CAS (Content-Addressable Store)

Fester exposes a shared CAS API for cross-project artifact caching:

- `PUT /api/cas/{sha256}` — store an artifact (SHA-256 verified server-side)
- `GET /api/cas/{sha256}` — retrieve an artifact
- `HEAD /api/cas/{sha256}` — check existence
- `DELETE /api/cas/{sha256}` — remove an artifact
- `GET /api/cas/` — list all artifacts (paginated, filterable by target)
- `GET /api/cas/stats` — cache statistics

## Security Model

Fester is designed to run behind existing network controls (OPNsense, IPFire,
or any firewall appliance). There is no built-in authentication layer — the
network is assumed to be trusted. For public exposure, use a reverse proxy with
authentication (nginx + OAuth2 Proxy, Traefik + Authelia, etc.).

## Port Assignment

- **8181** — Fester backend (FastAPI + WebSocket + UI)
- **8787** — Node agent probe port (HTTP health + metrics endpoint)

## Coding Standards

- Python 3.12+ with type hints and modern syntax.
- All imports use the `backend.X.Y` prefix (no bare imports).
- Events are emitted via `bus.emit()` — never mutate state from request handlers.
- UI is vanilla HTML/CSS/JS with no build step and no framework dependencies.
- CSS uses design tokens defined in `style.css` (dark theme only).

## Version History

| Version | Date       | Summary                                      |
|---------|------------|----------------------------------------------|
| 0.1.0   | 2026-06-25 | Initial project structure, stubbed modules    |
| 0.2.0   | 2026-06-27 | Real FastAPI backend, 7-page UI, WebSocket   |
| 0.3.0   | 2026-06-28 | Storage layer, tmux, cause graph, debugger   |
| Unreleased | —       | BTC 0.4.0 integration, CAS API, SSE4_2 ISA  |