# Handoff — `flan emit --x86` annotated, so its output can be read

Branch `dev-loop`, from `f772162`. **Stub: written before the code, per the working rules. Kept updated as
the work lands.**

The x86 backend exists so that a dev build is ours end to end and so that the editor can be told *why* each
instruction is there. Until now `flan emit --x86` printed a three-line file header and then nothing but
`.byte` blobs: no source form, no frame key, no statement of the calling convention, nothing naming the
bookkeeping. Reading it meant `as` plus `objdump`, and even that only answers *what*, never *why*.

## What is being built

1. **A comment per Flan form**, carrying the form's own source text and its `file:line:col`, above the run of
   bytes that form produced. `lower`'s existing `dwline` hook is the annotation point — every expression
   already passes through it carrying `e.Tast.loc`.
2. **A frame map per function.** `-0x20(%rbp)` means nothing without a key, and the key exists: `fn.snames`
   says what the source called each slot, `f.slots` says where each one landed, and `xfer_off` / `sret_off` /
   `retval` name the three the compiler adds. This is the single biggest difference from an LLVM listing.
3. **The calling convention, stated per function** — which register each argument arrived in, where the
   transfer channel is, whether there is a hidden `sret`.
4. **The bookkeeping named**: the post-call guard, the bounds-check triple, the indirection cell load in a
   `--dev` build, `rep movsb` block copies, the prologue and the epilogue.

## The two decisions

**Annotation is always on for `flan emit --x86` and always off for a `--x86` build.** `flan emit` exists to be
read by a person; there is no reason to make a reader ask for the thing the command is for. A build's `.s` is
a temporary file handed straight to clang and read by nobody, so leaving it exactly as it was keeps
`survey.sh`'s 103 MATCH a statement about the same text it has always been. `--no-annotate` is accepted by
`emit --x86` for the one consumer that wants the old spelling, which is the byte-identity check below.

**None of this belongs to the LLVM path.** `flan emit` already prints IR that names its values, carries
`!dbg` on every instruction and `!DILocalVariable` on every slot. The problem being fixed here is one this
backend has and LLVM does not.

## Byte identity

Annotation must not change one byte of emitted code. Comments and the splitting of one `.byte` directive into
several are both invisible to the assembler, but "invisible" is a claim to be measured rather than asserted:
for every program in the corpus, emit both ways, assemble both, and compare each section's bytes.

`survey.sh` at 103 MATCH / 0 DIFFER / 0 REFUSED and `dune test` are the regression check on the edits to
`buf` and `lower` — they say the backend still compiles what it compiled — and the section comparison is the
check on annotation itself.

## Status

Stub. Nothing below this line has landed yet.