# Cache mapping and replacement — reproducible teaching experiment

A small **read-only, address-trace-driven cache model**, written in JavaScript with no runtime dependencies beyond Node.js 20+. It explores a practical computer-architecture question: *why do two caches with the same total capacity sometimes behave differently?*

## Reproduce

```sh
node --test projects/cache-lab/cache.test.mjs
node projects/cache-lab/experiments.mjs
node projects/cache-lab/experiments.mjs --write
```

Run from the portfolio repository root. `--write` regenerates the checked-in `projects/cache-lab/results.json` from the same fixed input sequences. All simulation and test source is public here, not hidden behind a demo.

## Architecture and assumptions

- 32-bit unsigned **byte addresses**; block index = `floor(address / lineBytes)`.
- Set = `block index % number of sets`; tag = `floor(block index / number of sets)`; offset = `address % lineBytes`.
- Parameters: total capacity, line size, associativity (ways), and LRU or FIFO eviction. Supported values are positive powers of two no larger than 1 MiB, with at least one full set.
- Cold lines are allocated before eviction. Hits refresh recency for **LRU**; FIFO does not update insertion age.
- Hits, misses and evictions are counted. No probabilistic randomness is used in the experiments.

**Not modeled:** write-back/write-through, dirty bits, MESI/coherence, memory latency, prefetching, pipeline stalls, timing, or realistic application traces. A high hit rate in a synthetic trace is **not** a measured speedup. The model is not a synthesizable RTL cache.

## Evidence and test coverage

The Node test suite checks block offsets and mapping, compulsory/collision misses, associativity, replacement-policy differences, invalid inputs, trace parsing, deterministic behavior, and fixed-seed randomized traces. The randomized test compares results against an **independent array-based reference model** across eight cache configurations. This is useful functional checking, **not proof of exhaustive correctness**.

The experimental traces are deliberately small and synthetic. They isolate spatial locality, set conflicts, a repeated working set, and LRU versus FIFO. The `results.json` file contains machine-generated counts for every combination.

## Further work

Add write policies and per-access read/write events, a trace input CLI, larger trace sets, and compare against a cycle-accurate RTL implementation. These are future directions—not implemented features.