Last updated: 2026-11-22

U
Undergraduate level
EPH
Ephemeral / Tooling โ€” Knowledge that evolves in months to a year โ€” check for updates

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)StageGate units at the end
3โ€“5 NovNew compiler and runtime; language suite without globals; v2 compiles itself to a fixed pointSuites run one after another
5โ€“7 NovSurvey of the 418 programs at the tag; gaps closed; suites run on the v2 enginesโ€”
7โ€“14 NovRemoving Rust: the IR and its Python reader, WebAssembly from v2, the site and portfolio builders on v2โ€”
14โ€“16 NovWorlds; the playground, REPL and IDE on v2; parallel gates; selftests on v2 alone229, then 335
18โ€“19 NovCode review findings; measured speed-ups; bytes; scenarios that carry their programs621 at v2.0.0
20 NovLinux executables (v2.1.0)859
21โ€“22 NovShowcase programs, HTTP beyond the machine, TLS cryptography as packages965

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

WhereOld shapev2 shape
The Gherkin runner and the language suiteStep registry and scenario state in globalsAn explicit context object (ctx_* in lib/gherkin)
signals, queue, build_progressset_varState held in the virtual file system
lib/x64_asmA named Dict object shared across assembliesA vec local to each assembly
pegA cache outside its contextThe cache in its context
build_portfolioTwo top-level lets read from functionsFunctions; 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.

ProgramsFailure on v2CauseOutcome
31declared twiceA program defined a name the runtime also hasAllowed: the program's calls reach its own definition (#243)
16undefined variable unitunit was a value in pat and a free name in v2. build_site and build_portfolio were among themunit is the unit value unless bound (#244)
7undefined variable ASTSyntax definitions built nodes through ASTAdded to the spec (#242)
6A contract in apply_substparadigm_gallery demos wrote flat facts, ["has_wood", "yard"], against 40+ nested uses elsewhereFacts are nested only; the demos were changed (#240)
3no method X for YA string naming an object could set a field but not read it; new was given extra arguments for inheritanceBoth reads and writes work through a name; class ... inherits (#241)
4Bare undefined namesrust-runtime/examples tested the Rust runtime; oo_logic_mix asserted that a bare X reads as itselfLeft as they were: bare names stay an error (#245)
9Include not foundInclude paths to files that no longer existPrograms 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 behaviourWhat depended on itFix
pat printed a program's last top-level valueSynthesis selftests compared whole outputA 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 fieldEarly v2 gave false for both a missing field and a stored false; wd_isolation, named_objects and interp_run_selftest were written against itget 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 timeA file included twice ran its top level twiceEach 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 outputsMany programsKept, and written into spec 1.13
The include line's whole remainder was its pathNo comment could follow an includeThe 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 pat and patc1. From 7 November the suites start programs on the v2 compiler and interpreter through lib/v2_engines.patlang.
  • Scenarios that called the old x64 runtime's internals (rt_print_i64 and others) were rewritten to check the same behaviour from the language.
  • The synthesis selftests interpreted with pat.exe and compiled with patc1.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_team and friendly_cli still 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 found lean_run.patlang calling to_str and random_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.

WhereIssueFix
Gherkin runnerFeature files were built a byte at a time, so a step containing รฉ reached the matcher as รƒยฉ and no step matchedFiles are read as text; a scenario covers two-, three- and four-byte characters
Build-cache readerRecords were read byte by byte, and non-ASCII names came back wrongRead through str_intern's handle with sc_substr
utf8 and lean selftestsInteger division gave a rational where the code expected an integerDivisions floored
Linker, cache, deflate, zipA list of ints spends sixteen bytes of memory on each byteA 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 packageutf8_encode encoded a character at a timeA 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.

OperationCauseBeforeAfter
s = s + x in a loopCopied the whole string266ย s0.18ย s
let xs = list_push(xs, f(xs))The push copied the list when another argument read itLinear after the fix
Adding 8,000 rulesrule_add did not add in place, and every goal visited every rule8,784ย ms69ย ms
plan() with 511 goalsGrew as n3546ย s12ย s
new() with 400 classesClass found by a scan848,000 cycles72,000 cycles
Reading the 512th field of an objectFields scanned in order169,000 cycles2,700 cycles
VFS append, 8,000 filesNo hashed table; each append rebuilt the file's text33.6ย s0.02ย s
16 threads taking one lockWaiters did not yield while waiting36ย s0.6ย s
Harmonic number H(2000) in rationalsBigint division and rational addition, replaced by Knuth's Algorithm D and Henrici's method131ย s0.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 its if conditions until the return.
  • Includes in a browser. A program with an include had 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 found when 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_site and build_portfolio stopped on unit in 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:

AreaIssueFix
SocketsThreads sharing a listener could deadlockListeners are non-blocking for life; accept waits with WSAPoll
Socketstcp_connect reached any addressLoopback only, unless the program declares tcp_allow_remote() (added 21 November)
ProcessesChildren inherited every handle; exec_capture would run a program planted in the working directoryChildren inherit only their pipes; exec_capture searches PATH itself
PathsA path holding a NUL, or one leaving the VFS flush directory, was used as givenThe program stops, or the flush refuses
ExecutablesLoaded at a fixed baseA base relocation table and a randomised base
MemoryReleasing a deep structure recursed until the stack overflowedFinalizing is iterative
ComparisonNaN compared as ordered; exact division by zero did not stopNaN is unordered and unequal; exact division by zero stops the program
TextMalformed UTF-8 and surrogates passed throughMalformed bytes read as U+FFFD; chr refuses surrogates
Parsingnot bound looser than and/or; exponents misread; lines in strings not countedFixed, with errors that name their line
ThreadsA vec changed by two threads at once went undetectedThe 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.