# LESSON_LEARNED — mgf-fedres

> 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 — The schema is the authority; the Python enums only mirror it

- **Context:** the M0 contract ships the state vocabularies in two places — the
  JSON Schemas (`schemas/_common.schema.json`, the wire authority) and Python
  `StrEnum`s (`states.py`, what code imports).
- **What I learned:** having the same closed enum in two artifacts invites drift.
  The fix is to make one the authority (the schema) and pin the other to it with a
  test (`test_sync_states_match_schema` asserts `SYNC_STATES` / `TEST_STATUS_VALUES`
  equal the schema `$defs`). The Python copy exists only so code needn't re-parse
  JSON to know the closed set — it is a mirror, not a second source.
- **Why it matters:** a silent enum mismatch would let an invalid wire value pass
  Python checks (or vice-versa), defeating the whole fail-closed posture.
- **How to apply:** any new closed vocabulary goes in the schema first, then mirror
  + pin. Never edit one side alone.
- **Generalizes?:** yes — single-authority + a lock-step test for any value
  duplicated between a wire schema and code.

---

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

- **Context:** `mgf-fedres` scaffolded as a conformant federation sibling — the
  shared spine for `mgf-fed-web` + `mgf-test-web`.
- **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).

---
