# LESSON_LEARNED — mgf-test-web (ProofWarden)

> Append-only, dated log of non-obvious lessons learned working in this repo.
> Newest first. One entry per lesson. Supersede a wrong past entry with a new
> one — never rewrite history. Federation rule: **DOC-19**.

---

## 2026-06-29 — Single-flight is won by construction, not by a lock

- **Context:** the A4 spike's whole job is "a given test can never run twice at
  once, regardless of launcher". The tempting implementation is a lock file
  (`O_EXCL` / `flock`) every caller checks before running.
- **What I learned:** a file lock has a check-then-act TOCTOU and leaks on crash
  (the holder dies, the lock never releases, everything blocks forever). The
  warden dodges both by being **one process**: the acquire decision
  (`free → grant` / `same test+config → coalesce` / `else → queue`) is an
  in-process critical section under a single lock — there is no second decider to
  race. Crash recovery is a **lease** (heartbeat + TTL + an *audited* reclaim),
  not a bare lock, so a dead holder is reclaimed visibly, never silently stolen.
- **Why it matters:** the property is enforced *by construction*, so it holds for
  every origin (CLI / web / agent / CI) the moment they all reach the **same**
  warden over the UDS — not by everyone politely remembering to check a lock.
- **How to apply:** keep the broker the only place that decides run-state; never
  add a "fast path" that runs a test outside it (the client **fails closed** when
  the warden is down for exactly this reason). Every acquire/coalesce/queue/reclaim
  stays an audited event — that audit *is* the proof the authority worked.
- **Generalizes?:** yes — when a property must hold across many uncoordinated
  callers, funnel them through one authority and make the decision a single
  critical section, rather than asking each caller to self-police a shared lock.

---

## 2026-06-29 — File seeded (repo creation)

- **Context:** `mgf-test-web` scaffolded as a conformant federation sibling — the
  testing & CI authority (ProofWarden) on top of the `mgf-fedres` spine.
- **What I learned:** (seed entry).
- **Why it matters:** lessons left only in chat transcripts evaporate.
- **How to apply:** add a dated entry when you hit a gotcha or reusable technique.
- **Generalizes?:** n/a (seed entry).

---
