Joseph Ferano
57fe91f303
FIX.org, NEXT.md, DISCUSS.org, docs/DISCUSS.md and the session handoff at the root are one TODO.org now: 293 entries under seven subsystem headings, each carrying an org keyword that says where it stands. A DONE entry is a few lines saying what was decided and what that rules out; the reasoning that would not compress — the embedding spike and the four reports the hand-written x86 backend was built from — moved into docs/BUILT.md instead, and its entries point there in one line. Every entry was checked against the tree before it got a keyword, and the prose was wrong in both directions. Things the deleted files called open were built: the first-evaluation stall, main being redefinable, macro parameter lists, the type-limit constants, the array constructors, the byte fills, inc/dec, the discard's fontification, the Emacs buffers, rt_die's _exit, the backtrace surface, and the acceptance failure that could print and still exit zero. Things they called done were not: the backend reports' no-plan buckets had gone stale in the other direction, the value-dependent defvar was superseded rather than built, and macro-expansion source locations are on an unmerged lane, so that entry is NEXT and names the branch. Every comment that cited one of the five by name now cites a heading that exists, in TODO.org or in docs/BUILT.md. The session reports under docs/handoffs/ keep naming the files they worked on, because rewriting them would falsify what those sessions did; each carries a note saying where the content went.
7.0 KiB
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 TODO.org, plan.org, 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, ../TODO.org at the root for every decision, open question and known gap — one heading
each, with a keyword saying where it stands — 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. |
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
Each of these was written once, from a reading or a measurement, and is not maintained afterwards. They are kept because the reasoning in them is the reason the code looks the way it does, and deriving it again would cost more than reading it.
| 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. |
SPIKE-INFERENCE.md |
Whether the checker should infer more than it does. A reading rather than a branch: nothing was built. |
SPIKE-DYNAMIC.md |
The dynamic-value runtime — NaN-boxed values over a mark-sweep heap. The design the dyn type and runtime/flan_dyn.c were built from. |
SPIKE-DUPLICITY.md |
Where the dyn side and the native side meet, and where one of them repeats the other. The source of the rule that a capability is written once per side and never twice on the same side. |
SBCL-REDEFINITION-NOTES.md |
What SBCL does when a struct is redefined under a running image, read out of the clone. Written for the open question of whether Flan's hard refusal should become a warning and a kept old layout. The question is still open. |
BUGS-2026-09-18.md |
A five-agent sweep of the runtime, checker, backends, dev loop and Emacs client. The bugs are fixed; the file is kept because spec-memory.md cites one of its findings as evidence. |
DISCUSS.md used to be here and is gone. Its open questions are entries in
../TODO.org now, one heading each; the four long reports it carried — the
embedding spike and the three that built the hand-written x86 backend — are in
BUILT.md, under "One process" and "The hand-written x86 backend, and the four
measurements behind it", because they were reasoning rather than decisions and
a few lines could not hold them.
Three more files that used to be here are gone, and git log is where they
live now: overview.md, the first brainstorm from before the language had
S-expressions, which had said in its own first line that it was superseded;
DIAGNOSTICS-AUDIT.md, the worklist the diagnostics rewrite was done from,
which the rewrite closed; and REVIEW-production-readiness.md, a review of a
tree a thousand commits behind this one.
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 ../TODO.org,
because the reasoning behind a guard or a calling convention is often only written down once and this is
where it was written.
Nine of them are the hand-written x86-64 backend, read in the order the work happened:
HANDOFF-x86-rt.md set the remaining-items list the others close, HANDOFF-x86-redef.md
built the redefinition emitter, HANDOFF-x86-aggregates.md took that across the struct boundary,
HANDOFF-x86-guards.md settled the two guards nothing reaches, HANDOFF-x86-debug.md added debug
information, and HANDOFF-x86-cost.md measured what the backend costs and set the survey running on its
own so a refusal cannot sit unnoticed again. Then HANDOFF-x86-devloop.md for making it the dev loop's
default, HANDOFF-x86-abi-marker.md and HANDOFF-x86-annotate.md, and
HANDOFF-x86-macro-visibility.md for why a macro module's symbols are hidden.
The rest are unrelated to each other. HANDOFF-arith.md is why a divide by zero is a condition
rather than a SIGFPE. HANDOFF-raylib-ports.md is the running record of the last two raylib example
ports, whose lasting findings were folded into PORTING.md, and 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. HANDOFF-devtest-noise.md is the linker
error dune test used to print on every run. 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. HANDOFF-dyn-m1.md is the first milestone of the dynamic
runtime, HANDOFF-lowering-buffer.md the buffer that shows what a form lowered to, HANDOFF-rot.md a
sweep for prose that had stopped being true, and HANDOFF-tidy.md is this reorganisation.