# Mission: Compiler & metaprogramming fundamentals

> **Draft** — written from the opening conversation. Correct me where I've guessed.

## Why

Martin is building [`pydantic-codegen`](https://github.com/MartinBernstorff/pydantic-codegen):
a tool that treats a Pydantic model as the single domain source of truth and derives
FastAPI payloads, service-layer payloads, projections, sum types, and Django models from
it. It already works. The goal now is to stop making design decisions by instinct — to
know *which* decisions are the load-bearing ones, what the field already calls them, and
what is known about getting them right. No formal CS background, so the vocabulary gap is
real and it makes the literature hard to enter.

## Success looks like

- Can justify the shape of `ir.py` in one paragraph, in terms other compiler people
  recognise — and can say precisely which future feature would force it to change.
- Can read a compiler paper (nanopass, hygiene, elaboration) and map every term in it
  onto something in `pydantic-codegen` or explain why it doesn't apply.
- Can ship a `fake()`-constructor generator that is correct about Python's import-time
  default evaluation, mutability, recursive models, and definition order — and can
  explain each of those four hazards from memory.
- Recognises when a `re.sub` over source text is standing in for a missing IR node.

## Constraints

- Real project, real deadlines: every lesson must cash out as a decision or a diff in
  `pydantic-codegen`. No toy languages.
- Strong practitioner, zero formal grounding — expect fast uptake on mechanism, gaps on
  naming and on the literature.
- Repo has hard conventions (see its `CLAUDE.md`): no comments, no primitives as
  parameters, `iterpy` pipelines, tests beside code. Lessons should respect them.

## Out of scope

- Machine code, register allocation, SSA, optimisation. This is a source-to-source tool;
  the backend ends at text.
- Parser construction (LR, PEG, combinators). Python hands him a parser for free.
- Type inference / unification. He reads annotations; he does not solve them.