NEXT.md: the ring, the seqlock, the break loop's exit and the leaked handle are
struck with what each was fixed to rather than only that it was. The snapshot
generation stays open — it wants a hook a test can drive, which is a design
decision and not a fix. The four-buffer paragraph is now two and two.
BUILT.md carries the reasoning that outlives the change. "Nothing is ever
dlclosed" is restated as "nothing that published anything is ever dlclosed",
because that is what the rule was always about — being pointed into — and the
two modules that are closed are the ones nothing can point into. Stating it the
weaker way is what made a dropped handle look like obedience.
The agent section gains why a full ring refuses rather than drops or blocks,
and why the break loop leaves with _exit. The renderer section gains why the
result counter had to become a real seqlock and why marking it odd needs a
release fence rather than a release store — a release store orders what
precedes it, so the buffer writes could still be hoisted over it, which is the
original bug with more ceremony.
One correction: the release-build story named flan_dev_result_get as the symbol
that came up undefined. That symbol no longer exists.
dune test green; dune build @sanitize clean.
The language half of §3's parameters is in; the half that makes it worth
having is not. A break loop chooses by position and has nothing to fill a
clause's parameters in with, and that is now the top item in NEXT.md,
spelled out end to end — the accessors the frame can already answer, the
signature on the wire, and the one store that has to happen before the
channel is aimed.
§3 asks for a clause's report string to be settled before parameters and
it was not. The field is cheap and so is the accessor; the only thing
that would read either is the break loop's listing, which lives in the
agent and the daemon, so it would have shipped as a field nothing read.
It belongs with the editor half, which is changing that listing anyway.
BUILT.md gains the section on the third target and corrects the claim it
already carried: emscripten_set_main_loop had the browser fact right and drew
the wrong conclusion, because asyncify answers the same fact without cutting
main in half.
NEXT.md gets the four holes. sand.flan has no web build, and the proximate
cause is that vendor/agent/flan_agent.c:426 uses struct timeval without
pulling in sys/time.h, which glibc gives it transitively and emscripten does
not; sand's main calls agent/start unconditionally so Reach cannot prune it.
Beneath the include is the decision worth making rather than patching around:
the agent is a socket server and the browser has no sockets, so the honest fix
is to refuse vendor:agent on a web target the way --dev is refused.
Assets are two questions and only the easy one is about emscripten.
--embed-file is a linker argument and so already expressible as an @web line.
The hard one is that the file doing (rl/load-texture "brush.png") is
structurally the one file that cannot say so: Load hands out lflags only for a
directory package, and main is not exported, so a program can never be one. No
flag was invented for it.
And nothing has been opened in a browser, asyncify's cost is quoted rather
than measured, and audio and threads on web are untried.
Step 2 claimed (Vec T) unblocks (fn [c] (push errors c) ...) and it does not.
check.ml's captured reads ctx.outer only to raise a better refusal and lookup
never reads it at all, so closure capture — spec-memory.md's case 2 — is
unbuilt. And the same spec captures a Vec by pointer rather than by value,
a split no capture path has needed because every capturable type today is a
value type. Two separate items, named as such under step 2.
Item 1 stops restating the four decisions and points at the section holding
them, keeping only the consequence the build order turns on. The Carp line
numbers were checked and are right, so they come out of the bug entry.
(:op "layout" :type T) needs no running program: the daemon owns the build, so
Tast.structs is already in the session it compiled the process from. The open
question was what T is, and it needs no new machinery — Load qualifies every
declaration at import, so two packages' Missing are a/Missing and b/Missing and
the name is the type id. Emit already writes that same qualified name into
flan_error, so the string break reports as :condition resolves as :type by
construction, which is the round trip the test makes.
A bare name is refused with the candidates rather than resolved to a unique
suffix: resolving it would put back the ambiguity the rule exists to remove.
spec-memory.md settled them and NEXT.md kept asking. Ranked item 1 now states
the decisions and points at the section that holds them.
The build order is new. An allocator is a procedure plus a data pointer, and
check.ml refuses function values four ways as milestone 5, which reads as
milestone 6 depending on milestone 5. It does not: every one of those refusals
is about surface syntax, and the compiler already builds function values no
Flan type names — a handler-bind clause reaching flan_handler's fn pointer, and
a dev build's call through an indirection cell. So Allocator is a builtin
opaque type and the built-in allocators need nothing from milestone 5. A
user-written one does, because it needs a defn's name in value position.
Also recorded: 5 and 6 interleave, since the macro expander is blocked on union
values; the operation table has free-all and no retain-capacity, which Zig
splits and a frame arena wants; and two line citations in the Allocators
section point at the wrong place while the claims they support are true.
The manual described the signature-change refusal as though it were the
design. It is not, and session.ml already said so at the refusal: a
signature change should make a new version, leave old callers on the old
one, and warn at the stale sites. plan.org calls it signature generations
and stale-caller warnings, and it is milestone 7's unfinished half.
The struct-layout rejection is the decided one and stays. Conflating them
made a placeholder look like a rule.
ASan was instrumenting none of the Flan half: it is an LLVM pass that
only touches functions carrying sanitize_address, which clang's C
frontend adds and hand-written IR does not. Globals get redzones either
way, which is why it looked right. emit.ml puts the attribute on every
define now, and a control asserts the report.
UBSan reaches no Flan code and no flag changes that -- its checks are
frontend-emitted branches, not a pass -- so shift UB and the NaN cast are
not answerable this way. Left as a compiler question, pinned by a control
that must not report.
A negative index into a global is silent in bounds.flan, which is
measured. "Because a global has no left redzone" was the explanation
put on it, and it does not survive the obvious test: declare another
defvar in front of arr and arr[-1] is caught, landing in that global's
right redzone. Underflow detection is a question about what the linker
put in front of the object, not about the access. Corrected in
test_sanitize, BUILT.md and NEXT.md.
NEXT.md's entry also goes back to its stated size. It had grown to 78
lines saying what BUILT.md says in the same commit range -- the
attribute, the -O0 decision, the bounds.flan table -- which is the
half-build-log the file's own header warns about. What stays here is
what is next: the UBSan gap as an undecided compiler question, the four
daemon-path buffers the corpus never reaches, and Valgrind.
NEXT.md's queued section becomes a landed one. The headline is not the
flag: ASan reaches Flan code only because Emit now attributes every
define, and UBSan reaches none of it and has no lever that would, so the
shift-UB and float-cast items that section listed are still open and are
a compiler feature rather than a flag.
The clean result is written with its reach. println.flan pushes a
1100-character string through escaped[1024] on purpose, so that buffer
is genuinely covered; scratch[64] never sees more than 20 characters;
and the 4K result cap, the dev registry guard, SNAP_MAX/SNAP_NAMES and
condition_name[128] are on the daemon path and not in the corpus at all
-- read, not tested. Two defects fixed, both found by reading. Three of
bounds.flan's six out-of-bounds cases caught with the checks off, with
the other three tabulated and explained, and the caveat that ASan sees
out-of-object and not out-of-subobject access, so three of six is a
ceiling and not a measurement.
BUILT.md gets the durable half: the attribute, the absent UBSan lever,
why --sanitize does not force -O0 when --debug does, and the -O0/-O2
divergence that earned it.
sin and cos in the prelude rather than copied per file, with the caveat
sqrt does not have: IEEE-754 makes sqrt correctly rounded and requires
nothing of the kind for sine, so these are the one place the prelude may
disagree bit for bit between native and wasm32. A program hashing output
across targets must not route the hash through one.
Arithmetic folds left over as many operands as you write, and so does the
constant folder, which otherwise refused (defconst n (* 2 3 4)) after the
checker had accepted it. One operand is refused by name: there is no unary
minus, and the message points at (- 0 x), which is what the prelude writes.
The typed let binding is a grammar question and is written up rather than
guessed at. The break banner premise had gone stale -- check.sh already
runs that demo under a timeout and keeps what it printed.
Looked at annotating a let binding and stopped at the surface syntax,
which is the whole of the problem. Everything underneath is already
built: bindings carry a type, load renames through it, and the checker
consumes it as the want for the value. What is missing is a way to write
it that a parser with no types can read -- let is a flat list of pairs,
so it cannot disambiguate by argument count the way defvar and defconst
do, and [4 rl/Vector2] is a perfectly good array literal.
So NEXT.md gets the three candidate surfaces and a recommendation rather
than a commit picking one: give zeroed its type as an argument. It is one
branch in the checker, no new syntax, and it answers the case that
actually hurt -- a fixed array with nothing to infer from -- without
contradicting plan.org's "annotate function signatures, infer locals".
The two items beside it in the same ranked list are marked fixed.
The .out file and the two places that quote it in prose had the banner
from before restarts were numbered, so check.sh had been red on
breakdemo since that commit. The .out is regenerated from the same
build --dev and timeout run check.sh does, rather than typed: the leading
blank line and the three spaces before each number are part of what is
compared.
The page gets a sentence it was missing. A number in front of a restart
is not decoration -- a restart is taken by position, because an inner one
can shadow an outer one of the same name -- and the banner showed the
numbers without the page ever saying what they were for.
print and println are the whole printing surface now. About 500 call
sites across 47 files, and the site documents either of them for the
first time.
Two pinned outputs moved and both are corrections. sand-headless hashes
to 15595743031174623232 rather than -2851001042534928384 -- the same 64
bits, printed unsigned now that hash-grid's u64 no longer goes through an
(i64 ...) cast, which is the bug the family's explicit widening invited.
And a trap column shifted because the call it names got shorter.
NEXT.md was 1,738 lines and about half of it narrated work that was
finished. BUILT.md takes that half — the reload primitive, cells, the
agent, the session, the daemon, the Emacs client, conditions, the FFI
shim, the layout, and the order it was all built in. Not deleted,
because the reasons in it are load-bearing and would have to be derived
again.
NEXT.md keeps what is left, and says at the top what the two files are
for, so it does not become a log a second time. The struck-through
milestone checklist goes with the log; its one live item, the milestone
4 loose ends, stays. Start here was stale in three places and is
rewritten: conditions are three steps of four, a restart is taken by
position, and find-restart is blocked on a type rather than on effort.
The raylib gap list and the reasons break was declined are written down
where the next session will look for them, rather than living in a
commit message.
A let-bound local is its own name under lldb now, and a redefinition
module carries DWARF when the daemon was asked for it.
Resolved against the println track in session.ml: the thunk keeps the
render walk's appended slots and gains the names beside them, the walk's
own scratch having none to keep.
Emit.redefinition has taken ~debug since it was written and was tested
with it; Session.eval never passed it, so every body installed by C-c C-c
lost its debug info in the running process.
Passing it alone would have been half a fix. Build.shared is what forces
-O0, and dev.ml built modules at -O2, so the llvm.dbg.declares would have
been emitted and then deleted by mem2reg: a line table, and no locals.
And a module with DWARF loaded into a host without it lines up against
nothing. So it is one flag — flan dev --debug and flan reload --debug —
and it sets the host build, the module builds and the emitted metadata
together. Off by default: a debug build is an -O0 build, and quietly
making every reloaded body -O0 changes the frame time of the one function
you are iterating on, in the loop whose point is watching that number.
What a dlopen'd module does to a breakpoint, measured against the reload
fixture rather than reasoned about:
- lldb reads the new module's DWARF on the dlopen and says so: "1
location added to breakpoint 3".
- A breakpoint set by NAME gains a second location either way, so
dlopen was never the difficulty. What the line table buys is that it
stops with source instead of disassembly.
- A FILE AND LINE breakpoint on the new body resolves only with it;
without, it sits at locations = 0 (pending) forever.
- A FILE AND LINE breakpoint on the HOST's copy stays pinned at
locations = 1. That is correct, not stale: the old body is still
mapped and every call site that has not gone through its cell again
still reaches it.
- The stack crosses intact — a frame in the reloaded .so and the one
below it in the host each name their own .flan file.
(lldb) frame variable
(long) step = 10
(long) prior = 11
The transcripts are in flan-dape.el, replacing the note that said the
module carries no DWARF yet.
flan-cnr.el's stack pane was refusing for the wrong reason. DWARF was
never its gap; nothing is attached to the stopped program, and a socket
cannot read another process's frames. Reworded to say that.
Source interleaving in the disassembly buffer is unblocked and not done:
objdump -dS interleaves a --debug module's Flan source correctly, so
Dev.asm_of needs the -S and a parse_listing that tolerates source lines.
The first ten of raylib's core list, ported. Seven new bindings and the
named colour palette; nothing else was added, because a binding called
by nothing is the same as not having bound it.
The gaps they found are the point. No number reaches draw-text: i64->bytes
answers [u8], draw-text wants a string, and nothing bridges — five of the
ten wanted TextFormat and got a glyph table instead. And an enum parameter
cannot be driven by a loop variable: the index is an i32, the parameter is
an enum, neither converts, and a second declare-c with an i32 face is
refused because one C function gets one binding. Two correct rules that
compose into a wall.
None of the gaps expected blocked anything: no generics, no allocator, no
Vec, no escaping closure, no block-scoped defer. These are input-and-draw
programs over fixed-size state, which is the shape the language has.
A restart the innermost frame shadows could be seen and not taken;
it is taken by position now, off a snapshot that stopped moving under
the break loop. The editor half this was briefed as building already
existed — the stale line that said otherwise is fixed.
The snapshot made the listing stand still; it did not make the handoff safe.
A choice is validated against the snapshot on top when the request lands and
resolved against the snapshot on top when the game thread next looks, and
between those the loop runs evaluations — one that errors pushes a break of
its own, whose loop reaches the flag first and takes its own index 2 for the
one somebody picked off the outer list. That is the failure this change exists
to end, arriving by a different door.
So each snapshot carries a generation, a choice carries the generation it was
validated against, and a loop claims only what is addressed to it. A mismatch
is left set rather than dropped: the listener already answered ok, so the break
it was meant for must still be able to take it. Depth could not do this — an
outer break resuming and a new one starting reuses the number. The snapshot is
also popped before the depth comes down now, so the two never describe
different breaks.
The client's own new path gets tested too: the candidate table is pure, so the
shapes a real daemon will not easily produce are checked directly, and the
break-and-resume test now goes through restart-at rather than by name.
flan-dev-unreachable-restarts was dead on arrival — flan-break reads
:unreachable off its own reply — and is gone.
nth removed, and the REPL's structural walk lifted into a println that
shares it. The example of the narrowing-index rule used nth, which no
longer exists.
spec-conditions.md §4 gains the rule the shadowing bug was hiding: a handler
matches by name, a debugger identifies by position, and the two are not the
same question. With it, the snapshot — a position means nothing against a
stack that moves — and the fact that a visible restart may still be
unreachable, which §6's explicit lowering makes possible.
§3 records the open one: a clause should carry a report string.
is what invoke-restart needs and not what a person reading a list needs. It
wants settling before restarts with parameters, which is where a bare name is
least sufficient.
conditions.org had the break loop under "Not yet", which it has not been for
some time, and now says why find-restart and compute-restarts still are: they
are blocked on a Restart type and a list to return one in, not on effort.
Two CIDER-shaped buffers: C-c C-i navigates a value, C-c C-b shows the
condition, the restarts and the stack. C-c C-M-b keeps the old one-key prompt.
The inspector needs no protocol change at all. eval-expr already answers a
rendered string, and Session.render writes exactly seven shapes, so that string
is a grammar. Navigation is a stack of *expressions* rather than of handles:
going into :pos sends (.pos b), into element 2 sends (at (.tags b) 2) - both
ordinary Flan a person could type. CIDER keeps its stack on the server because
a JVM value can be retained; nothing here can, since a Flan value has no header
and the render thunk is dlclosed the moment it returns. The view is therefore
never stale, where CIDER's shows the object as it was when you pushed. What it
buys over C-x C-e is the depth-4 span-8 bound: a field past it comes back as
... and nothing recovers it from the echo area, and re-rooting renders it from
depth 0.
SBCL decided the order - condition, restarts, then stack - because invoke-debugger
prints the condition and show-restarts and then stops; the backtrace is a command
you type. The restarts are the decision and the stack is the explanation for it.
And SBCL found a live bug. show-restarts omits the bracket on a name already
used further in, which is not decoration: §4 takes the first frame offering a
name, so a second frame offering retry is real, is on the list, and cannot be
chosen. The old prompt showed retry twice and sent the string either way, and
the inner frame took it silently. restarts.flan's own nested function has been
that counterexample since the transfer landed. The buffer draws the shadowed row
unbracketed and refuses RET on it by name, with a test asserting nothing was
sent - which stops the lie without restoring the choice. Taking a restart by
index is the fix and is recorded as such.
Sections that cannot be filled are drawn saying why rather than omitted: a
missing section cannot be told from an empty one, and only one of those is a
fact about the program.
C-c C-a disassembles a named function, C-u C-c C-a shows its LLVM IR, and the
daemon keeps a name-to-origin table filled only when delivery answers ok, so it
knows which module owns a name after N reloads.
The honest part is the basis line. It cannot claim "installed now": the agent has
no verb that reports an address, the cell lives in the program's address space,
and eval-expr renders a pointer as <ptr>. So the reply says which of three things
is true - nothing delivered, delivered and queued, or delivered while stopped -
and prints it above the first instruction. The stopped case first read "not
installed yet", which was wrong: the commonest way to stop is to install a body
and have it error.
Overlays clear on the next command in that buffer, through a buffer-local
pre-command-hook installed with the overlay and removed with it. Not
post-command-hook, which fires at the end of the failing command and would clear
the overlay before redisplay.
NEXT.md gains a "Blocked and unfinished" section, which is the point of this
commit. Everything in it was found, decided or half-built this session and then
stopped, and each entry says what blocks it: the four memory questions the Odin
and Carp studies converged on, typed restarts, handler-case, six bugs with
repros, the mutation pass's remaining blind spots, four things that are one line
away, and three places the normative documents contradict the code.
Three drifted claims fixed while there. The file said "There is still no REPL.
Nothing does redefinition, dlopen, or nREPL" in a document that spends fifteen
sections describing exactly those; the raylib inventory said 29 calls against
164; the commit count said 34 against 154.
At -O0 it stores into read-only memory and takes SIGSEGV; at -O2 LLVM deletes
it as undefined and the program prints the unmodified string and exits 0. Same
source, and which way it fails depends on a flag, which is worse than either
outcome on its own.
Nothing refuses it and nothing cheaply can: bytes turns a string into a [u8],
the language lets you write through a slice, and by then nothing records where
the bytes came from. That is provenance, which plan.org defers as open decision
#3. Emitting literals as mutable globals is not a fix - it moves which flag
misbehaves and costs their read-only placement.
Written down rather than half-fixed, with the rule the string lane already
follows: a function over a string must not write through it.
screen-width and screen-height went from 1400x1000 to 900x600, and the first
colour changed. Those are defconsts the checker consumes to size rows and cols,
so the grid is a different shape and the hash over it is a different number.
Updated rather than reverted: the change is deliberate and the hash is a
regression test for the simulation being reproducible, not for it being any
particular size.
Checked the way the old number was: -2851001042534928384 on native and on
wasm32, byte for byte. A hash that moved on only one target would mean the
change had broken reproducibility rather than the grid, which is the thing this
case exists to catch.
NEXT.md rewrapped to a wider column - a reflow, not a rewrite. The three TODO
entries in it are the substance: live disassembly of what is actually installed
in a cell, error overlays that vanish on the next thing you do rather than
surviving until an evaluation is accepted, and CL-style interactive recovery
where a stopped program offers a typed restart and the editor asks for the
value before invoking it.
flan-mode's declare-functions become real autoloads. A declare-function only
quiets the byte compiler; it does not load anything, so a user who had loaded
only flan-mode could not invoke M-x flan-dev at all.
vendor/raylib has no C in it any more: shim.c is deleted and its 84 wrappers
are emitted from declare-c, which names the library's function in the library's
own signature. The reason the shim exists is unchanged - a small struct's
calling convention is a per-target classification and clang reproduces it for
free - but writing it by hand has stopped.
declare-c is a second form rather than a change to declare, because the two make
opposite claims about the same shape: (declare start-raw [path string] ...) says
the symbol takes ptr+len, and (declare-c init-window [... title string] ...)
says it takes a NUL-terminated char*. No structural rule separates them, so the
author says which.
The merge needed two fixes that neither lane could have found alone.
Load's uses-walker matches decl_kind exhaustively and did not know DeclareC, so
the reachability work and the generator did not compile together.
And the generated C is now emitted in parts keyed by the wrapper's own C symbol,
not as one translation unit. Reach.link drops the bindings nothing reachable
calls; a single TU holding every wrapper referenced every raylib symbol, so
sand-headless - which deliberately links no libraylib, and is the reason Reach
exists - failed at the link with undefined references to GetTime and its
neighbours. The first attempt keyed the parts by Flan name and broke the other
way, dropping a wrapper that was called: the flattened declaration is named
foo-c when a Flan wrapper is generated over it and foo when none is needed, so
the Flan name is not one thing. The wrapper's C symbol is what the declaration
binds in both branches.
Worth recording how close that came to passing: the acceptance suite died with
an exception rather than printing FAIL, so a grep for failures counted zero and
the suite looked green. Only the count of reporting suites - ten where there had
been eleven - showed it.
Two gaps in what was claimed. The first is prose: "the typedef follows the
defstruct" answers field order and field types but says nothing about
padding, which reads like the remaining hazard. It is not one. Every field
type the generator admits has the same layout under LLVM as under C, and
emit.ml writes no datalayout, so clang applies the target's own rules to
both halves; everything where they could diverge — an array, a slice, an
Option, a map, a union — is already refused at the field.
The second is real. The flattened declaration's name is invented by
appending -c, so a hand-written foo-c beside (declare-c foo ...) came out
as the checker complaining that a name not in the file was declared twice.
Refused now where it happens, naming both and saying to rename one.
Every refusal is by name with the reason, so the tests assert on the
reasons and weakening one to a bare "cannot" breaks them: a slice, an
Option, a union, a fixed array, a map, a returned string, a callback, an
unknown type, a struct field C cannot hold, and two Flan names for one C
symbol.
The rest is text about text, which is the honest scope: what a wrapper
does is settled by clang, and what is worth checking in OCaml is the
shape of what clang is handed. Two cases assert the typedef's field
order against a defstruct and against the same defstruct permuted,
because only the pair rules out a generator that sorts — and sorting is
exactly the mutation the raylib cases cannot see, since every raylib
struct is fields of one size and a rename changes no offset.
What the raylib cases do see is a permuted defstruct, and that was run:
Rectangle width/height, Vector2 x/y, Image width/height, Image with data
moved last, Texture2D id/format, Color r/a and Camera2D offset/target
all go red. Texture2D width/mipmaps stays green, which is what NEXT.md
already says headless cannot pin — the one green is the control, not a
gap.
Clojure's backtick, tilde and tilde-at rather than Common Lisp's comma forms:
is_delimiter already treats a comma as whitespace and every binding vector in
the corpus assumes it, so freeing the comma would rewrite more of the language
than macros are worth. They read as (quasiquote x), (unquote x) and
(unquote-splicing x), the way 'x already reads as (quote x) - the reader stays
dumb and the meaning is resolved later.
The backtick previously read as an ordinary symbol character, which is exactly
the failure the reader's own header warns about for the apostrophe. Both sigils
are delimiters now, so a~b is two things and can never be one name.
defmacro validates its shape before refusing, because a malformed one and a
well-formed one are different mistakes and deserve different sentences. The
three new reader names are refused by name too, or they would fall through to
Call and come back as unknown name quasiquote. unquote outside a quasiquote is
refused as a mistake rather than as a milestone, since the reader cannot know
where it is.
Nothing is stored: no Ast.Defmacro and no macro table. A new decl variant would
have forced edits to four files other agents hold this session, and a
process-global registry spanning the prelude parse, the package parses and
hundreds of test snippets would make results order-dependent. The storage shape
is the expander author's first decision anyway.
The design note records what the expander needs, and the blocker worth knowing:
a macro is [Form] -> Form, so Form has to be a Flan union whose layout the
compiler and the loaded macro agree on exactly, and union values are milestone
6.
Every sigil in the corpus test sat in leading position, where read_form
handles it before is_delimiter is ever consulted — so reverting the
is_delimiter line alone left every case green. a`b now has the case a~b
already had, and the corpus carries both, which is what makes the class
guard cover the delimiter change rather than only the read branches.
The handoff note hedged on the one thing it exists to decide: expansion
runs over Form before Parse, not over Ast. There is no Ast.Defmacro, so
an Ast pass would have nothing to read. Says milestone 6 for union
values because that is the number check.ml itself gives.
The front half is here and the back half is not, and the reason is that
running a macro means compiling it and dlopening it into the compiler —
which is Emit.redefinition plus Build.shared, already measured at ~19ms,
pointed at our own process instead of the program's.
The part worth recording is what blocks it: a macro is [Form] -> Form,
so Form has to be a Flan union with a layout the compiler and the loaded
macro agree on exactly. That is milestone 6 work landing before
milestone 5's, and it is bigger than the expander.
Nothing is stored on purpose. No macro table and no Ast.Defmacro: a
table nothing reads is where a design rots, and the storage shape is the
expander author's first decision rather than one to inherit from a lane
that could not test it.
NEXT.md described a packaging system with no visibility, no nesting and a link
that ignored the program, and explained sand's two files by it. All four are
now wrong. The Packages section says what the rules are; a new section says how
the link is decided and why the pruning has to take the functions as well as
the flags; and the sand section keeps the part that still stands — the headless
test needs no window on any target, which is a reason for two entry points and
never was a reason for two files.
The comments in load.ml and session.ml that used sim.flan to explain package
qualification now use vendor/agent, which is the package left with a defn in
it.
sand-headless prints 2256461126764447066 on native and on wasm32, at -O2 and at
-O0, in one dune test run. That is the whole point of the exercise and the
reason rand-f32 is written in Flan rather than bound to libc.
The old note said the builtins archive has to come from a wasi-sdk release. It
does not: emscripten builds the same compiler-rt and it links correctly under
the other name. It is a different triple built by a different clang, so it is a
substitution rather than the real article, and both the code and the note say so
- nobody should read "wasm32 works" without knowing which joint is glued.
Two findings the note did not have. The entry point is __main_argc_argv, not
main, and the link succeeds before trapping on a signature-mismatched weak stub.
And the target has to reach the C compiles as well as the link, since flan_rt.c
includes stdio.h.
Also corrects why sand is two programs. Two claims had been run together: raylib
does work on wasm through emscripten, and a game loop is expressible there with
emscripten_set_main_loop - a different main, not a different program. What
justifies the split is only that a headless test needs no window on any target.
What makes it mandatory is Load collecting a package's C and link flags whether
or not anything references the package, and that is the thing to fix.
Image first and deliberately: it is CPU-side, so it is the only large piece of
raylib that can be asserted headlessly rather than looked at. gen-image-color,
the pixel reads, both flips, a PNG round trip through export and load, and the
resize and crop dimensions and contents are all in the table at -O2 and -O0.
The shapes, text and timing calls are observed only, by running sand under Xvfb
and looking, and the program and NEXT.md both say which is which.
Five permutations were run red and restored: Image's width against height and
mipmaps against format, GetImageColor's two indices, the two flip wrappers
bound to each other, and the crop rectangle's width against height. The third
of those also broke the export and load lines, which is what makes the PNG
round trip verified rather than merely plausible.
Two corrections to the brief it was given. MeasureText is not headless material
- it measures with the default font, which only InitWindow loads, and a C probe
returns 0 - and the same is true of the frame-time and screen-size calls. And
the raylib.h on this machine is 5.1-dev while the linked library is 5.5, so
every signature was checked against nm -D instead: IsImageValid rather than
IsImageReady, and DrawRectangleRoundedLines takes no thickness.
Font loading is refused by name. A Font carries a Texture2D, a Rectangle* and a
GlyphInfo*, and a GlyphInfo carries an Image - two more aggregates and two owned
arrays, for something with no headless test.
The section on what a headless FFI test can and cannot pin was written before
anything CPU-side was bound, so it had no example of the one shape that beats
store-and-return: scalars in and struct fields out, with nothing for a
permuted layout to cancel against.
It also did not say that MeasureText answers 0 without a window, which is the
assumption this lane started with and had to measure its way out of. Two
lanes have now guessed the same thing.
Item 6 said the builtins archive has to come from wasi-sdk. It does not have
to, and what is standing in its place is emscripten's compiler-rt for a
different triple — which works, and is worth writing down as a substitution
rather than leaving as "wasm32 works".
The break loop was reachable from a raw socket. This is the half that makes
it reachable from an editor, and it all follows from one fact: a program
stops at a moment nobody asked about.
So the state is learned twice, on purpose. It rides on every reply, beside
the program's output and for the same reason -- the likeliest instant for a
program to stop is the one just after an evaluation, which is a reply the
client is already reading, and learning it a second later from a poll would
mean learning it after the echo area had said the evaluation was fine. And a
timer asks anyway, once a second with `describe', because a program that
stops in a frame of its own game loop produces no reply at all and folding
state into replies that never come says nothing. The timer never reconnects
-- that would quietly erase the `lost' state that exists to be seen -- and
skips while a request is in flight, since accept-process-output runs timers
and a poll firing inside a read would eat that read's reply.
Three ops: `break' for the restart names, `restart' and `abort'. The
annotation owns :stopped and :condition rather than the ops, so one place in
the daemon decides whether the program is stopped and the poll and the prompt
cannot disagree. "ok" from `restart' means accepted, not resumed: the choice
is validated against the stopped stack and taken when that thread next comes
round, so it says so and the client clears its own flag rather than polling
once, finding it stopped, and re-opening the prompt it just answered.
The agent grew one verb, `status', answered in both states. Everything else
the break loop offers is refused while running, rightly; but the question an
editor asks without already knowing had to have an answer either way or there
would be nothing to poll.
And flan_agent_poll had to become re-entrant, which was a bug rather than an
addition. A C-x C-e thunk may itself error, and the break loop that catches
it polls again from inside that call. The old loop cached both indices and
stored tail at the end, rewinding over everything the nested poll consumed --
re-running the thunk that had just stopped the program, which is an unbounded
recursion of breaks. Each job is now claimed before it is run. test_dev.ml
evaluates an expression that errors and resumes it, which fails against the
old shape.
