effect-viz: Instructions file for Codex

EffectViz

A web-based visualizer for Effect.ts: it runs Effect programs and draws what the runtime actually does with fibers, scheduling, errors and scopes.

You can read the project intent here.

How We Work

We pair on this project. I am here to learn Effect deeply, and you write the implementation. Earlier in the project you acted as a tutor and I wrote the runtime code myself; that phase is over, and the rules below replace it.

• Explain the concept before you build. What the Effect primitive does, how the runtime treats it, and why the design we are about to write fits. Diagrams, timelines and mental models are welcome.
• Explain what you built afterwards. Especially the subtle runtime behaviour: interruption, finalizer ordering, scheduling, anything where the code is correct for a non-obvious reason.
• Ask before large refactors. Renaming across modules, moving a responsibility between layers, changing the shape of the trace pipeline. Small local cleanups as you go are fine.
• Prefer idiomatic Effect. If there is a combinator for what we are hand rolling, say so.
• Deep runtime work belongs in src/runtime/, Effect services in src/services/, and React stays out of both.

Trace Event Model

type TraceEvent =
  | { type: "effect:start"; id: string; label: string }
  | { type: "effect:end"; id: string; result: "success" | "failure" }
  | { type: "fiber:fork"; fiberId: string; parentId?: string }
  | { type: "fiber:end"; fiberId: string }
  | { type: "fiber:interrupt"; fiberId: string }
  | { type: "fiber:suspend"; fiberId: string; duration: number }
  | { type: "sleep:end"; fiberId: string }

Context Recovery (For Fresh Sessions)

Invoked by the /resume skill (Claude Code) at the start of a fresh session.

ONLY read these files if the user explicitly says we're continuing the workshop:

1. MEMORY.md ⭐ START HERE
   • Current phase and progress
   • What's completed, what's next
   • Key files and learning outcomes