Last updated: 2026-11-22
Porting to PatLang 2.0: Issues by Stage
For new readers
Between the pre-v2 tag of 2 November 2026 and the v2.1.0 release of 20 November, every program, library, test suite and browser demo in the PatLang repository moved from the old engines (the Rust pat interpreter and the patc1 compiler) to the v2 compiler and interpreter. This page lists the issues that move met, grouped by stage, with the cause of each and what was done. The language changes themselves are listed in What changed since v1; this page covers what broke when existing material met them.
The stages Ephemeral / ToolingKnowledge that evolves in months to a year โ check for updates
| Dates (2026) | Stage | Gate units at the end |
|---|---|---|
| 3โ5 Nov | New compiler and runtime; language suite without globals; v2 compiles itself to a fixed point | Suites run one after another |
| 5โ7 Nov | Survey of the 418 programs at the tag; gaps closed; suites run on the v2 engines | โ |
| 7โ14 Nov | Removing Rust: the IR and its Python reader, WebAssembly from v2, the site and portfolio builders on v2 | โ |
| 14โ16 Nov | Worlds; the playground, REPL and IDE on v2; parallel gates; selftests on v2 alone | 229, then 335 |
| 18โ19 Nov | Code review findings; measured speed-ups; bytes; scenarios that carry their programs | 621 at v2.0.0 |
| 20 Nov | Linux executables (v2.1.0) | 859 |
| 21โ22 Nov | Showcase programs, HTTP beyond the machine, TLS cryptography as packages | 965 |
The Linux work has a page of its own, PatLang 2.0 beyond Windows, and the issues found in the test gates themselves are in Issues found in the v2 gates.
Globals out, contexts in Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
v2 has no global variables, so every library that kept state in set_var or set_global had to carry it some other way before the language suite could compile on v2 at all.globals carry hidden state contexts make it explicit
| Where | Old shape | v2 shape |
|---|---|---|
| The Gherkin runner and the language suite | Step registry and scenario state in globals | An explicit context object (ctx_* in lib/gherkin) |
signals, queue, build_progress | set_var | State held in the virtual file system |
lib/x64_asm | A named Dict object shared across assemblies | A vec local to each assembly |
peg | A cache outside its context | The cache in its context |
build_portfolio | Two top-level lets read from functions | Functions; q and nl moved to lib/chars.patlang |
The old compiler's own runtime and fixtures kept their globals until that compiler was retired. A repository scan for globals ran inside Part 2's compiler-structure feature at first, which made Part 2 depend on self_hosting/tools; it moved to the repository suite on 16 November.
What the survey of existing programs found Ephemeral / ToolingKnowledge that evolves in months to a year โ check for updates
On 5 November the 418 programs that existed at the tag were compiled with v2, and those with no side effects were run on v2, its interpreter and pat. 347 compiled. A second run on 6 November, after the gaps below were closed, compiled 385.
| Programs | Failure on v2 | Cause | Outcome |
|---|---|---|---|
| 31 | declared twice | A program defined a name the runtime also has | Allowed: the program's calls reach its own definition (#243) |
| 16 | undefined variable unit | unit was a value in pat and a free name in v2. build_site and build_portfolio were among them | unit is the unit value unless bound (#244) |
| 7 | undefined variable AST | Syntax definitions built nodes through AST | Added to the spec (#242) |
| 6 | A contract in apply_subst | paradigm_gallery demos wrote flat facts, ["has_wood", "yard"], against 40+ nested uses elsewhere | Facts are nested only; the demos were changed (#240) |
| 3 | no method X for Y | A string naming an object could set a field but not read it; new was given extra arguments for inheritance | Both reads and writes work through a name; class ... inherits (#241) |
| 4 | Bare undefined names | rust-runtime/examples tested the Rust runtime; oo_logic_mix asserted that a bare X reads as itself | Left as they were: bare names stay an error (#245) |
| 9 | Include not found | Include paths to files that no longer exist | Programs fixed or retired |
Of 174 programs run in the second survey, 97 printed the same as pat. Many of the 77 that differed printed timings or reported errors in pat's own format, so the survey could not use plain output comparison as its pass mark. The same survey found two wrong results with no error: bnot 0 gave true where pat gave -1 (#235), and every thread shared one word for system-call counts, so read_file_bytes could return another thread's count (#249).shared state breaks isolation guarantees
Behaviours programs depended on without stating them Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
The hardest issues to find were tests and libraries that passed because of an old engine's incidental behaviour.
| Incidental behaviour | What depended on it | Fix |
|---|---|---|
pat printed a program's last top-level value | Synthesis selftests compared whole output | A run passes when its output starts with the expected lines, which holds on either engine |
Unit printed as "" | GOAP synthesis libraries tested absence with "" + get(...) == "" | Tests use == unit. This brought back the missing-snippet errors and the literal-argument wiring the old test had hidden. A repository check now refuses the "" + get( form |
get gave unit for a missing field | Early v2 gave false for both a missing field and a stored false; wd_isolation, named_objects and interp_run_selftest were written against it | get gives unit again (16 November); spec 1.5 states what every lookup gives when nothing is there |
| The old compiler spliced an include's text every time | A file included twice ran its top level twice | Each file is included once, before the files that include it; friendly_cli expands includes once |
A function with no return gave its last statement's value; exec_capture merged both outputs | Many programs | Kept, and written into spec 1.13 |
| The include line's whole remainder was its path | No comment could follow an include | The path is the text between the quotes (#264), through one helper shared by the front end, the include expanders and the dependency graph |
Tests and programs that started the old tools Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
A test that starts pat.exe or patc1.exe as a subprocess passes only on a machine where those were built, so each one had to be found and moved before Rust could leave the build.
- Language scenarios that compared engines spawned
patandpatc1. From 7 November the suites start programs on the v2 compiler and interpreter throughlib/v2_engines.patlang. - Scenarios that called the old x64 runtime's internals (
rt_print_i64and others) were rewritten to check the same behaviour from the language. - The synthesis selftests interpreted with
pat.exeand compiled withpatc1.exe. Six of the 29 were missing from their runner's list. All now run on v2 as gate units. - The block-model suite ran on the old route's engine. Its longest scenarios took 83 and 28 minutes and set the floor of a full gates run. It was retired from the gates on 16 November, and the eleven library selftests it ran moved to
run_selftests.patlang, at 2 to 25 seconds each. - The examples,
coverage_main,agent_teamandfriendly_clistill started the old tools until 20 November (#266). A repository check now fails on any program that starts a retired tool, apart from an allowlist that gives a reason for each entry. - A names suite (
v2.exe --names) checks that every demo and gated selftest calls only declared names. Its first run foundlean_run.patlangcallingto_strandrandom_int, neither of which v2 has, and writing under/tmp.
The language scenarios kept their programs in separate fixture files, which made it possible for a scenario's steps to pass without the program they named being run. Every language scenario now states its program in a Gherkin doc string, with what both engines print (#269), and the steps that did nothing were removed. That was the last change before the v2.0.0 tag.Gherkin keeps specs executable, not just readable
Text, bytes and character counts Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
v2 strings count characters, and code that read text one byte at a time met that rule in several places.
| Where | Issue | Fix |
|---|---|---|
| Gherkin runner | Feature files were built a byte at a time, so a step containing รฉ reached the matcher as รยฉ and no step matched | Files are read as text; a scenario covers two-, three- and four-byte characters |
| Build-cache reader | Records were read byte by byte, and non-ASCII names came back wrong | Read through str_intern's handle with sc_substr |
utf8 and lean selftests | Integer division gave a rational where the code expected an integer | Divisions floored |
Linker, cache, deflate, zip | A list of ints spends sixteen bytes of memory on each byte | A bytes class, one byte of memory a byte. Linking the interpreter: peak working set 1.84ย GB to 0.56ย GB. deflate on 2ย MB: peak 301ย MB to 93ย MB |
sha256 package | utf8_encode encoded a character at a time | A string is already held as UTF-8, so its bytes are copied out whole: a quarter of the cycles |
Packages were also caught by line endings: their manifests hash every shipped file, so .gitattributes keeps packages/ LF on every checkout, and the bytes checked out are the bytes hashed.
Costs that grew with the input Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
Programs that were tolerable on pat met quadratic or worse costs in v2's first runtime. Each fix below was measured before and after.
| Operation | Cause | Before | After |
|---|---|---|---|
s = s + x in a loop | Copied the whole string | 266ย s | 0.18ย s |
let xs = list_push(xs, f(xs)) | The push copied the list when another argument read it | Linear after the fix | |
| Adding 8,000 rules | rule_add did not add in place, and every goal visited every rule | 8,784ย ms | 69ย ms |
plan() with 511 goals | Grew as n3 | 546ย s | 12ย s |
new() with 400 classes | Class found by a scan | 848,000 cycles | 72,000 cycles |
| Reading the 512th field of an object | Fields scanned in order | 169,000 cycles | 2,700 cycles |
| VFS append, 8,000 files | No hashed table; each append rebuilt the file's text | 33.6ย s | 0.02ย s |
| 16 threads taking one lock | Waiters did not yield while waiting | 36ย s | 0.6ย s |
| Harmonic number H(2000) in rationals | Bigint division and rational addition, replaced by Knuth's Algorithm D and Henrici's method | 131ย s | 0.56ย s |
The compiler met the same class of problem in its own PatLang, covered in The v2 toolchain.
Browser demos and the site Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
The portfolio's demo pages and the site builder moved to v2 between 8 and 15 November. Each step had its own issue.
- WebAssembly without Rust. v2 writes modules from its IR with its own encoder. Threads and fibres are Web Workers over one shared memory, which needs a cross-origin isolated page; the demo pages carry a service worker to provide it.
- Locals. Each IR slot first had a pair of WebAssembly locals of its own. Slots that are never live together now share a pair: the compiler's 62,487 slots need 16,960 pairs. One function,
rt_big_frame's__main, still keeps 3,005, because the ownership stage holds itsifconditions until the return. - Includes in a browser. A program with an
includehad no file system to read from. The host takes a read-only file bundle, so the playground, REPL and IDE compile the user's text with the runtime's files and run it in a fresh world. - Undeclared host functions. A call to a function the browser host lacks compiles, and stops with
host fn 'X' not foundwhen reached. - The debugger. The IDE now steps through a trace the interpreter records from calls the lowering inserts, after the program has run.
- The site builders.
build_siteandbuild_portfoliostopped onunitin the survey; after #244 they run compiled by v2, and every demo is built by v2 natively for its transcript and as WebAssembly for its page.
Engine bugs that porting found FoundationalKnowledge that endures for decades โ core principles
Running real programs on v2 found faults the specification's own scenarios had missed.
- A handler that yielded on a fiber held its event back for whoever resumed the fiber, since the list of running events belonged to the thread. Each fiber now has its own list.
- A program that asked for every runtime function by name reached its own registrations, which called themselves until the stack overflowed. The interpreter resolves by-name runtime functions from the list as it was when the program's table was made.
- A stop inside a world ended the program at first. It now returns a reserved mark that compiled frames test after each call, releasing what they hold on the way up; memory stays flat across 2,000 stops.
- A syntax definition was looked for only at line starts, so one inside an expression was missed.
- A parser fed a missing operand at the end of input, or before a closing bracket, hung. It now reports a parse error at the right line.
Found by the code review Ephemeral / ToolingKnowledge that evolves in months to a year โ check for updates
A review of the whole of v2 on 18 November found issues no failing test had pointed to. The main ones:
| Area | Issue | Fix |
|---|---|---|
| Sockets | Threads sharing a listener could deadlock | Listeners are non-blocking for life; accept waits with WSAPoll |
| Sockets | tcp_connect reached any address | Loopback only, unless the program declares tcp_allow_remote() (added 21 November) |
| Processes | Children inherited every handle; exec_capture would run a program planted in the working directory | Children inherit only their pipes; exec_capture searches PATH itself |
| Paths | A path holding a NUL, or one leaving the VFS flush directory, was used as given | The program stops, or the flush refuses |
| Executables | Loaded at a fixed base | A base relocation table and a randomised base |
| Memory | Releasing a deep structure recursed until the stack overflowed | Finalizing is iterative |
| Comparison | NaN compared as ordered; exact division by zero did not stop | NaN is unordered and unequal; exact division by zero stops the program |
| Text | Malformed UTF-8 and surrogates passed through | Malformed bytes read as U+FFFD; chr refuses surrogates |
| Parsing | not bound looser than and/or; exponents misread; lines in strings not counted | Fixed, with errors that name their line |
| Threads | A vec changed by two threads at once went undetected | The program stops |
Three suggested changes were measured and left alone: a thread pool for parallel_map, plain reference counts, and rewriting reused cache records, which was under 5% of a no-change build.
See also
What changed since v1 lists the language changes this page's issues came from. PatLang 2.0 beyond Windows covers the Linux and WebAssembly-under-Node targets. Issues found in the v2 gates covers the test infrastructure. The v2 toolchain describes the compiler, interpreter and gates as they now stand.
Graduate Attributes
Modelled on this page
- Researcher: Specific metrics and reproduction steps are recorded for every defect found during the migration.
- Critical Thinker: Proposed optimisations are measured against performance baselines before deciding whether to implement them.
- Reflective: The distinction between intended language behaviour and incidental engine quirks is examined to understand test failures.
University of Reading Graduate Attributes framework.