Repository navigation
A hotfix for 1.0.0, and the reason it exists is blunt: the Linux x64 artefacts of 1.0.0 do not start on most desktop processors. If you downloaded zelph-linux-x64.zip or zelph_1.0.0_amd64.deb and the binary died without printing anything, that was not your machine.
What was wrong
The build passed -march=native to the compiler in every GNU and Clang release build, so the published artefact demanded whatever instruction set the machine that compiled it happened to offer. GitHub's runner had AVX-512; a desktop processor generally does not, and the result is an illegal instruction before main is reached. Measured: 2082 AVX-512 instruction sites in the released libzelph.so, and none in a build of the same tag made on ordinary hardware.
The flag had been active since May 2025, so every release since then was a lottery. 0.9.6 through 0.9.9 happened to land on AVX2-class runners and worked. 1.0.0 did not.
Not affected: Windows and macOS, because MSVC has no equivalent flag and the macOS artefacts are arm64; and the AUR package, which builds from source on your own machine – which is also why the problem was invisible from there.
What replaces it
The build now declares the instruction set it targets instead of discovering one. ZELPH_X86_BASELINE defaults to x86-64-v3 – AVX2, FMA and BMI2, which every x86-64 processor from 2013 onwards has. A build for the machine you compile on is still available with -DZELPH_NATIVE_ARCH=ON; it is simply no longer what a release gets.
A declaration that nothing checks is a comment, so tools/check_arch_baseline.py opens a built binary and refuses anything above the declared floor. It reads the instruction ENCODING rather than disassembly text, because in 64-bit mode opcode 0x62 is the EVEX prefix and nothing else. Four ctest tests hold it: two probes that establish the check can tell an AVX-512 build from a baseline one, and the real checks against the library and against the zelph binary. The binary is checked separately because the bundled allocator is linked only there and carries architecture flags of its own – the one place a dependency could raise the floor was the one place a library check does not reach. Windows binaries travel to a Linux job for the same check, since MSVC builds have no objdump beside them.
The tests a package runs when you install zelph
The Chocolatey package used to run the entire suite on your machine, which is what made the 1.0.0 submission exceed the verifier's execution timeout. The suite is now split: 93 of 796 cases are marked slow, and packages run zelph_tests --test-suite-exclude=slow – 703 cases in about 20 seconds instead of nearly three minutes. tools/check_install_tier.py holds that selection to three properties, so it cannot be met by marking ever more cases slow: at least 80 % of all cases, no single case above 25 % of the selection, and a declared wall-clock budget.
Running a script
While fixing the above, one long-standing asymmetry was removed, and it changes output you may be relying on.
A file named on the command line used to be loaded the way .import loads a module: no echo of its statements, no deduction anchors, and inference deferred to the end of the file. It now runs as a session – exactly as if its lines had been typed, and identically to zelph < script.zph. That is what the shebang #!/usr/bin/env zelph always promised.
Three things follow, and all three were reported as separate defects:
- a bare
.node,.mermaidor.explainworks in a script file. It used to answer "no previous output node available", because the fallback is recorded when a statement is printed and nothing was printed; - deductions appear. With the default
focusfilter and no anchors, a script file wrote nothing at all to standard output for an ordinary reasoning run, while the same lines piped in printed the whole derivation; - inference runs after each line, so a line can read what the line before it derived.
A script named on the command line may also be called anything now – a shebang script is normally report, not report.zph – and .quit ends it where it stands. .import is unchanged: it still loads a module quietly, and still accepts only .zph and .janet.
zelph now tells you when something failed
zelph used to leave with status 0 regardless of what occurred. An .import that did not resolve wrote to standard error and carried on, and since the remaining statements usually answer correctly – because they never needed the missing module – the log looked entirely plausible while describing a configuration nobody had requested. That cost one user six weeks.
The process now returns a non-zero status when something failed, and a script that stopped early says so instead of simply ending. A warning that accompanies an operation zelph carried out as asked – the partial-view notice of a sharded load – is not such a case and does not affect the status.
A script reaching zelph on standard input stops at its first failing line too. Previously, only the file form did, and the piped form continued – so converting zelph < s.zph into zelph s.zph changed how much of a broken run you got to see. The two agree now: both stop, both say which lines were not read, and both leave with 1. A terminal is untouched, because there the question does not arise – nothing has been typed after the failing line yet, and stopping could only mean ending the session over a typo.
Better diagnosis
- A refused statement no longer poisons the session. A C++ exception leaving a Janet function skipped Janet's own unwinding, so a refusal the engine is right to raise could silently break the interpreter and surface much later as a bare "Janet error" pointing at correct code three imports away. Every zelph function reachable from Janet now converts an error into a Janet panic at the boundary.
- A statement that spans lines is named whole. The message used to quote the line that happened to complete the statement, which for a two-line rule is the half without the mistake.
- An unparsable statement says what the rule is. The grammar separates two values by whitespace, so a value glued to an opening parenthesis is not a statement;
f(x)is the shape everyone writes and it needs either the space or a notation island.%gets its own sentence, because it escapes a whole LINE to Janet and can never be a term – a value computed in Janet reaches a statement through the unquote,name. - A rule written without parentheses names the node in both roles, instead of reporting that facts with the same relation type and object are not supported.
- A byte order mark no longer destroys a script. The scan for a line's first character knew only space and tab, so a
.zphfile saved with a BOM lost its first line in silence: it was read as the beginning of a statement, stayed incomplete, and swallowed the line after it. A no-break space did the same, and an indented#line was parsed as a fact rather than a comment.
Deduction output
.deductions gains a fourth mode, quiet, and it is the new default. It filters exactly as focus does and shows exactly the same deduction lines – it only stops saying so, and marks the prompt with a + while the most recent run held something back:
zelph> .deductions quiet
Deduction printing mode: quiet
Only derivations about statements you entered are printed, and a run that hid any marks the prompt with '+' (e.g. "zelph+> ").
zelph> $(53 * 12) = X
(&53 * &12) = X
((&53 * &12) = &636) ⇐ {((&53 mul &12) prod &636) (&53 * &12) (:canonnum &636)}
zelph+>
The mark is the character +, and it is the fact rather than the count, because a number in a prompt reads as a running total and this is a per-run figure. It clears after a run that hid nothing, and it stands next to the - of a disabled auto-run — the part in front of the marks is the current language and changes with .lang. off carries it too, for the reason the - exists: it is a state you set and would otherwise have to remember.
Where a run does speak – focus, off, and any script named on the command line, which shows no prompt for a mark to appear in – it says one sentence:
Note: 130 deductions were hidden.
That is a rewrite in three respects. It is emitted once per run rather than before every printed deduction, so it carries the run’s total instead of the count since the last printed line. It goes to the same stream as the deduction lines it accounts for, so redirecting standard output can no longer keep an incomplete derivation and drop the sentence saying it is incomplete. And it no longer explains the mode: a run is only ever read in a mode you chose, and .deductions describes each mode’s effect where you choose it.
A deduction written to a file by .run-export is no longer counted as withheld; it used to report one hidden deduction for each derivation it had just exported.
The opening line changed with it, and stayed one line:
zelph 1.0.1
-- REPL mode - type .help for commands, e.g. '.help .deductions' to change what is shown --
.mermaid also takes the fact itself, the way .node and .explain do: .mermaid a rel b 2 is the fact a rel b at depth 2.
Upgrading
Drop-in. Nothing in the graph format, the standard library or the C ABI changed. If you script zelph, three things are worth a look: the exit status is now meaningful, a script named on the command line produces the output a piped one always did, and a piped script stops at its first failing line rather than carrying on.