# REA Learning-Loop Simulator (SimPy + NumPy)

## PURPOSE
Mid-video the creator pushes REA harder to make sense of Loom's Electron app: he uses
REA's **`trace` JavaScript-semantics command to resolve the 55 unnamed IPC channels**, and he
notes that before unbundling he "didn't find that much just in IPC operations," but afterwards
he got "a pretty good amount of data." That is the whole point of REA's **learning loop** —
ask, trace, read the evidence, ask a tighter follow-up. This project models that loop as a
discrete-event simulation so students can *measure* which strategy actually resolves more
channels per unit of analysis time.

## WHY THIS MATTERS
The video's honest framing is that REA is *not a magic wand* and *not a one-shot*. The loop
converges, but slowly, and each pass costs provider time. A simulator makes the tradeoff
concrete: blind single-pass tracing versus iterative, evidence-driven follow-ups.

## HOW TO BUILD
1. `pip install simpy numpy`.
2. Model the environment as a SimPy `Environment` with a single `analysis_provider`
   (`simpy.Resource(capacity=1)`) — the local provider the video says runs locally, one job at
   a time.
3. Represent **55 unnamed IPC channels** as objects with a hidden difficulty drawn from a
   seeded NumPy RNG (deterministic).
4. Each `trace` process occupies the provider for a sampled duration and resolves a channel
   only if the attempt's "evidence score" clears the channel's difficulty. Unresolved channels
   return as follow-up questions on the next pass.
5. Run three strategies — `single_pass`, `iterative_followup` (up to N passes), and
   `unbundle_first` (a one-off 40% evidence bonus mirroring the unbundle step) — and compare
   `time_to_resolve_all` and `channels_resolved`.

```python
rng = np.random.default_rng(seed=7)
channel.difficulty = float(rng.uniform(0.2, 0.9))
resolved = attempt_score >= channel.difficulty  # evidence must beat difficulty
```

## WHEN TO USE IN PRODUCTION
Use discrete-event simulation like this when planning any iterative agent pipeline where a
scarce, single-threaded tool is the bottleneck — deciding batch size, whether to pre-process
inputs, and when to stop looping. Do **not** use it to predict real decompiler accuracy; the
difficulty distributions here are illustrative, not measured from REA.

## HOW IT HELPS STUDENTS
They learn SimPy process/resource modelling, seeded reproducibility with NumPy, and how to
turn a qualitative claim ("REA is iterative, not one-shot") into a runnable experiment with
numbers behind it.

## STARTER CODE
See `starter/main.py` for the channel model, the three strategies, and a deterministic
`mean`/`resolved` summary printed at the end.
