PatLang: A Primer for Teaching Use

EverythingEverything you need to know before dropping any single "Journey" instalment into a session — without reading the other nine.

What PatLang is Ephemeral / ToolingKnowledge that evolves in months to a year — check for updates

PatLangPatLang 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.self-hosted: the compiler trusts itself

Two things make it unusually good teaching material:

1. 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.
2. 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 Applied / MethodologicalKnowledge with a 5–10 year half-life — stable practice

AA 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.
  Note well. When the same logic exists in more than one place, a fix applied to only one copy leaves the other silently disagreeing — this is 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.
  Note well. An "obviously cheap" variable read can silently clone an entire list or string under value semantics, turning a linear operation quadratic — this exact bug, or its fix going missing again, recurs at least five times across the series.

The series at a glance

TenTen 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.

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

EveryEvery 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.hypothesize, test, revise, over and over

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…").full pattern: the human-in-the-loop primer

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.

Companion framings of this same material

TheThe four short companion pieces below take the same underlying history and re-frame it for a specific reading purpose — use whichever fits the session:

• A Primer Before You Read the Journey Series — the student-facing version of this page: shorter, second-person, meant to be assigned directly rather than read by the instructor first.
• PatLang: A Primer, Read as a Crime Scene — frames each Act's investigation as forensic evidence-gathering, for sessions built around the detective-story angle.
• A Primer on Triangulation, Evidence, and Process — focuses on checking a project against several independent landmarks (its own implementation, the literature and the real problem), and on the evidence and process discipline that goes with that.
• A Primer on the Human in the Loop — focuses on the project owner's own interventions and pushback quoted throughout the series.

A separate companion, Instrumenting Long-Running Programs: Health, Progress, and Resume, covers the runtime-signals feature referenced in several later Acts in full technical detail.

Related Topics

• Goal-Oriented Action Planning (GOAP) — the game-AI concept behind the series' GOAP vocabulary, worked through from scratch with a minimal planner.
• TDD & BDD — the Given/When/Then discipline the induction/synthesis engine reads examples in, explained on its own terms.
• Risk Management: Lessons from Testing Real Systems — a companion page grounded in the same PatLang development history, applying the site's risk-management framework to real bugs from later in the series.