Joseph Ferano
3df49184a7
--dev --sanitize had been unbuildable for as long as a dev build has armed the registry from a constructor, and nobody knew because no alias built it: test_sanitize built the corpus twice and neither time --dev, test_dev builds --dev and never with a sanitizer. A configuration nothing builds can be broken for a month, and that one was. af71459 fixed it; this is what keeps it fixed. dev_sweep, in the alias that already exists rather than a new one -- five names to remember was already four too many, and this is the same question @sanitize is for. Seven programs built --dev twice, plain and sanitized, run standalone with no daemon: a sanitizer report fails, and so does any divergence from the unsanitized dev run. Standalone is what makes it nearly free, and it works because a dev build is not a dev session. The cells, the marker and the constructor are in the executable either way, and a program that never calls agent/start runs to its own end. That is why the list is mostly ordinary programs built the other way: dev-noagent is the only one of sixteen dev-*.flan that does not import the agent, and the rest stop in the break loop waiting for an editor, which is test_dev.ml's business against a real daemon. The three dyn programs are not interchangeable and the difference is the collector. dyn-vec allocates and never collects -- flan_dyn.c has a one-megabyte floor and dyn-vec does not reach it -- so what it says is that the registry and the allocator agree. dyn-map and p13-dyn-collect are the only two programs anywhere past that floor, so they are the only two under which a mark and a sweep run; without them a collection had still never happened in a dev build under ASan. dev_segv is beside the sweep rather than in it, because the program that faults cannot be compared against an unsanitized run: that build's handler prints its line and parks in the break loop, so the plain half would hang, and the two are supposed to differ. ASan is meant to own the fault -- flan_dev_crash_enable checks a weak __asan_init and stands down -- so the case asserts ASan's report and the absence of the handler's line. At -O0, because at -O2 the write through a bytes-view of a literal does not fault at all and both builds print the string unchanged. That yield had never run in any build anywhere; it was behind a link that did not happen. Checked both ways rather than asserted: eight failures with the constructor naming declarations again, clean with it fixed. Twenty-six seconds of the alias's 2m30 warm, and nothing added to dune test. Two aliases were also green only because dune test runs first. @sanitize never listed the package directories pkg-diamond.flan imports, and @page never listed sand.flan, which quotes.sh reaches through sand-headless.flan; from a cold tree the first died before its first sanitized build, and @page sits inside @checks where CI hides the same thing. Both listed now. @valgrind, @x86, @js and @cells were checked and are complete. What it still does not reach is in FIX.org: a program driven by a real flan dev daemon under ASan, which wants a --sanitize the CLI does not have and a way through Dev.serve. --x86 --sanitize is refused by Build by name, so there is no second backend to track here.
What is in here, and what is still true
These are the documents that are written once and read occasionally: the reasons behind the code, the
reports from finished investigations, and the record of individual work sessions. The documents that are
edited every day stay at the repository root, because source comments cite them by bare filename from
dozens of places and a path that moves is a path that rots. So plan.org, NEXT.md, spec-memory.md
and spec-conditions.md are one directory up, and everything here points back at them.
A note on how to read the citations below: a document in this directory that says plan.org means the
one at the repository root. Nothing in docs/ is named for a file at the root, so there is no ambiguity,
and rewriting a hundred prose mentions into ../plan.org would have cost more in readability than it
bought in precision.
If you have thirty seconds
Read BUILT.md. It is by far the largest document here and it is the one that pays: it holds the
reason behind every part of the compiler that exists, from why nothing is ever dlclosed to why the
printer is a compile-time walk over a type rather than a runtime function. It is current, it is
maintained, and deleting it would mean deriving all of it again. If you want to know why a thing is the
shape it is, the answer is in here.
After that, ../NEXT.md at the root for what is actually in flight, and REFERENCES.md here for
where the evidence comes from — the reference clones on this machine, what each one answers, and the
standing rule that a claim in these notes was read out of a clone rather than recalled.
The current documents
| File | What it is |
|---|---|
BUILT.md |
Why the parts that exist are shaped the way they are. The longest and the most load-bearing document in the repository. Current. |
DISCUSS.md |
Open questions, raised and deliberately not answered. Nothing in it is a decision or a task; entries that have since been answered say so and point at where the answer landed. Current, though it is half archive by now. |
PORTING.md |
What the author's game, siam-farmer, needs from Flan that Flan does not have yet, measured against the code that exists rather than against a plan. It is the requirements document the language is actually steering by. Current. |
REFERENCES.md |
The reference clones under ~/Repositories, what each one is consulted for, and the specific files and lines already cited from them. Current. |
The reports
| File | What it is |
|---|---|
SPIKE-GENERICS.md |
Milestone 5's parametric polymorphism, run early and out of order as a spike. The spike succeeded and generics landed, so this is the report of finished work rather than a live plan — but its findings about where the cost falls are still the reason the implementation looks the way it does. Historical, findings still stand. |
overview.md |
The first brainstorm, from before the language had S-expressions. It says in its own first line that it is superseded and no longer accurate. Kept for history only; its table of what changed is the only part worth reading. Superseded. |
handoffs/
One report per work session, each written by whoever held the branch at the time. They are the
operational record: what was attempted, what was measured, what was decided without being able to ask,
and what was left open for the next lane. They are all historical the moment they are written — a handoff
describes a session that has ended — but they are cited by name from source comments and from NEXT.md,
because the reasoning behind a guard or a calling convention is often only written down once and this is
where it was written.
Six of them are the hand-written x86-64 backend, read in the order the work happened:
handoffs/HANDOFF-x86-rt.md set the remaining-items list that the four after it close, handoffs/HANDOFF-x86-redef.md
built the redefinition emitter, handoffs/HANDOFF-x86-aggregates.md took that across the struct boundary,
handoffs/HANDOFF-x86-guards.md settled the two guards nothing reaches, handoffs/HANDOFF-x86-debug.md added debug
information, and handoffs/HANDOFF-x86-cost.md measured what the backend costs and set the survey running on its
own so a refusal cannot sit unnoticed again.
The other six sessions are unrelated to each other. handoffs/HANDOFF-arith.md is why a divide by zero is a condition
rather than a SIGFPE. handoffs/HANDOFF-raylib-ports.md is the running record of the last two raylib example
ports, whose lasting findings were folded into PORTING.md, and handoffs/HANDOFF-cimport-ptr.md is the arm
cimport.ml's header check had been promising in a comment and not implementing — which is what those two ports
found, worked around and wrote up. handoffs/HANDOFF-devtest-noise.md is the linker
error dune test used to print on every run. handoffs/HANDOFF-emacs-flake.md is the test_emacs flake that
turned out to be SIGPIPE killing the daemon mid-reply, and it is worth reading for the two mechanisms it
rules out as much as for the one it found. handoffs/HANDOFF-tidy.md is this reorganisation.