diff --git a/docs/handoffs/HANDOFF-x86-devloop.md b/docs/handoffs/HANDOFF-x86-devloop.md new file mode 100644 index 0000000..04ba70b --- /dev/null +++ b/docs/handoffs/HANDOFF-x86-devloop.md @@ -0,0 +1,36 @@ +# Handoff — the x86 backend, wired to the dev loop + +Branch `dev-loop`, worktree `agent-aaf84e55296df121c`, from `f459352`. This is items 1, 2 and 3 of +`HANDOFF-x86-redef.md`'s "What remains": the new-name path, the transient thunk, and the wiring that lets +`flan dev` choose the backend for a host and its modules together. + +**Status: in progress.** This file is written before the work rather than after it, so that a session that ends +early leaves its plan behind rather than nothing. + +## Why + +`llc` is 15–17ms of a ~19ms `C-c C-c` (`docs/BUILT.md`). The hand-written backend exists to replace that +number and has never been given the chance: `--x86` is read only by `flan build`'s argument list, and the +daemon builds both halves through LLVM. Until it is wired, the backend saves nothing. + +## The plan, in the order it will be committed + +1. **The new-name path** in `X86.redefinition`. A `slot` predicate beside `fnctx.ext`, a fourth `loc` case + for a module-local slot, `flan_dev_cell` / `flan_dev_global` calls in `flan_reload_install`, and an init + image for a new global. `test/test_reload.ml`'s v3/v4/v5 fixtures already exist and currently assert a + refusal; the transcript replaces it. +2. **The transient thunk**: `flan_reload_call` and the `@flan_reload_transient` marker, with an x86 analogue + of `emit.ml`'s `m.nstr` condition — a module that holds a string literal can never claim to be transient, + because the string outlives the call and the agent unloads the mapping. +3. **The wiring**: an `x86` field on `Session.t` and on `Session.change`, set once in `Dev.start` from + `flan dev --x86`, exactly parallel to `debug` — whose own comment already says why both ends have to come + from one flag. Never a fallback: if `X86.redefinition` refuses, the daemon reports the refusal. A silent + fallback to LLVM is precisely the crossed pair `flan.abi.x86` exists to refuse. + +## Decisions, recorded as they are made + +(to be filled in) + +## Measurements + +(to be filled in: emit / assemble / link / dlopen, both backends)