SysDeck/web/mini-services/fester/README.md

Fester — distributed DAG build orchestration

Fester is developed upstream as an independent repository. This copy is the vendored snapshot pre-integrated into the SysDeck master tarball — SysDeck ships with Fester wired in, no separate checkout required.

• Version: 0.2.1 (versioned independently from SysDeck 0.2.0)
• Runtime: Bun — bun install && bun run dev (hot reload)
• Transport: REST + raw WebSocket on port 3010
• Storage: SQLite timeline (fester.db, created and seeded on first boot)

Architecture

File	Role
engine.ts	PipelineEngine — DAG execution in topological waves, retries, CAS cache, BTC stamps, pause/step debugger
scheduler.ts	Weighted node scoring (cpu / temp / policy / instability)
nodes.ts	NodeStateRegistry + synthetic drift + the real local node
events.ts	EventBus + FesterEvent schema
store.ts	SQLite storage: builds / sessions / events / node states
autopsy.ts	Failure autopsy + propagation analysis
cause.ts	Causal graph builder
api.ts	REST surface (mirrors the upstream route table)
clock.ts	Engine tick loop
targets.ts	Project/target catalog
seed.ts	First-boot synthetic history (powers the replay views)

REST surface (abbreviated)

• GET /api/health — service status
• GET /api/builds, GET /api/builds/{id} — build list / detail
• POST /api/build — start a build {project, targets[], noCache?, retries?}
• POST /api/builds/{id}/cancel
• GET /api/targets · /api/nodes · /api/metrics · /api/policy
• GET /api/timeline[/{id}] · POST/GET /api/sessions
• GET /api/autopsy/{build}/{action} · /api/cause/{build} · /api/debugger/{build}

WebSocket: connect to ws://host:3010/ (or through a gateway at /?XTransformPort=3010). Full broadcast by default; {"type":"subscribe","buildId":…} for a single-build stream; {"type":"debugger","buildId":…,"command":"pause|resume|step"} for the interactive debugger.

Integration points

• SysDeck Web Edition — server-side proxy src/app/api/fester/route.ts plus the Fester sub-app (src/components/sysdeck/panels/festerPanel.tsx).
• SysDeck Cockpit Edition — bridge helper bridge/fester.py talks to this service over REST (see the cockpit tree in the master tarball).