PatLang: A Primer for Teaching Use
Everything you need to know before dropping any single "Journey" instalment into a session — without reading the other nine.
What PatLang is
PatLang is an experimental programming language built by one developer (with an AI assistant) as a real, working project — not a teaching toy invented after the fact. Its own compiler is written in itself ("self-hosted"), and it was deliberately designed to cover many different programming paradigms in one place: ordinary imperative code, object-oriented classes and traits, logic programming (Prolog-style facts and rules), goal-directed planning (GOAP), and event-driven programming.
Two things make it unusually good teaching material:
- It's a real project with a real commit history, not a curated set of clean examples. The "Journey" series (below) is written directly from that history — bugs, dead ends, wrong turns and all.
- It has three separate ways to run any program — interpreted, natively compiled, and compiled by its own self-hosted compiler — and a standing project rule that all three must produce byte-identical output before a feature counts as "done." This single design choice is why so many of the bugs in the series exist and were catchable at all: a single execution path would have hidden most of them.
You do not need to know PatLang's syntax to use any of this material. Every Act is written to be readable by someone who has never seen the language.
Vocabulary you'll need
A handful of terms recur constantly across the series:
- Self-hosting / the fixpoint — a compiler written in its own language, proven by getting it to successfully compile itself. "The fixpoint" specifically means: compiler A compiles a copy of its own source into compiler B, and B produces identical output to A on the same input.
- The three execution paths — interpreted (run directly, slowest, simplest), natively compiled (turned into a real executable, historically via Rust, later via a native x64 backend written in PatLang itself), and self-hosted-compiled (compiled by
patc1.exe, itself a compiled PatLang program). Bugs that only show up on one path are a recurring theme. - Mirror drift — when the same logic exists in more than one place (e.g. the interpreter's version of a feature and a textually separate copy embedded in the native code generator) and the two silently disagree because a fix was only applied to one. This is probably the single most-repeated failure pattern in the whole series.
- GOAP — Goal-Oriented Action Planning: given a set of actions (each with preconditions, effects and a cost) and a goal, a planner searches for a sequence of actions that reaches it. Borrowed from game AI (see the Games track's own GOAP page for the concept from scratch).
- The induction/synthesis engine — a system, built in PatLang, that reads Given/When/Then (BDD-style) examples and tries to derive real, working PatLang code that satisfies them, either by logical rule-induction or by GOAP-style search over small code fragments.
- No try/catch — PatLang has no exception-handling mechanism. This forces error handling to happen via returned values, disk-persisted state, or explicit checks — and is the direct cause of several of the concurrency and recovery bugs in the series.
- Value semantics — PatLang's variables copy-by-value by default. Repeatedly, an "obviously cheap" variable read turned out to be silently cloning an entire list or string, turning linear operations quadratic. This exact bug (or its fix going missing somewhere) recurs at least five times across the series.
The series at a glance
Ten instalments, chronological, each self-contained enough to read alone. Pick the instalment (or a single Act within it) that matches what you're teaching that week — you don't need to assign the whole series.
| # | Title (short) | Acts | Best used for |
|---|---|---|---|
| 1 | The Journey of Building PatLang | I–VI | Starting a project; the "100% tests passing" trap; an AI dev-team detour; multi-path verification |
| 2 | Teaching It to Write Itself | VII–XIV | Building a synthesis/induction engine; testing on real vs. toy data; performance regressions found and fixed |
| 3 | Hardening What Already Worked | XV–XXIII | Misattributed bugs; embedding a language in a new host; a three-act performance saga |
| 4 | Real Inheritance, at Last | XXIV–XXVIII | Scoping a big feature as a written, approved, sliced plan (classes/traits/inheritance) |
| 5 | Teaching It to Find Its Own Answers, for Real | XXIX–XXXV | AI/search evaluation honesty; vacuous results caught before being reported as wins |
| 6 | Taking the Native Backend Seriously | XXXVI–XLV | Silent-wrong-answer bugs vs. crashes; a stated project value overriding "clean" engineering advice |
| 7 | The Fixes That Weren't | XLVI–L | Fixes that never actually took effect; auditing your own "done" claims |
| 8 | Giving It a Window | LI–LVII | Interfacing with an external system (Win32); concurrency bugs exposed only once real threads exist |
| 9 | Searching Backward | LVIII–LXV | A* heuristics; honest negative results; "smallest program" vs. "the program a human would write" |
| 10 | Retiring the Last External Dependency | LXVI–LXVII | Two independent implementations disagreeing; diffing real output instead of guessing |
Each instalment ends with a "Lessons from this arc, the short version" bullet list — read that first to decide if a given page has what you want before reading the narrative.
How each "Act" is written
Every Act follows roughly the same shape, which makes them easy to extract and re-present:
Prompt or observation → investigation (often several wrong turns) → root cause found → fix → verification → a named, generalised lesson.
Many Acts also quote the project owner's own real messages verbatim (in italics) — these are worth keeping in any excerpt you use, since several of the best lessons come from the owner pushing back on an assumption ("are you putting arbitrary deadlines on things again?"), correcting a claim ("we do NOT want Rust backends"), or catching a mistake with plain scepticism ("looks rather open for something that's been closed…").
Where to send students for more
- Capabilities & Known Limitations — what PatLang can actually do today, without the history.
- Paradigms Guide — the language features themselves (OOP, logic, GOAP, events) explained from scratch.
- Live, runnable demos exist for several of the systems discussed in the series (REPL, hex-grid RTS, SQL console) if you want students to interact with the actual artefact a given Act is about.
A note on tone
The series is written in a distinctive, slightly wry, "warts-included" house style — it names its own mistakes plainly, including moments of being confidently wrong and getting corrected. That tone is doing real pedagogical work (it models the honesty this document's companion "teaching points" list draws on) — don't over-edit it out if you excerpt directly.