BFM-decomp/docs/portable-decomp-workflow.md

# The portable decomp workflow — a system anyone can run on any target

**Started 2026-08-24 (P31 S59). Living document.** This is the seed of the public deliverable: the
**system**, extracted from BFM and written so it applies to any byte-exact decompilation — any
console, any compiler, any language — by someone driving it solo.

Three sibling documents already exist and this one does not replace them:
`docs/accelerators.md` (what we learned late that day one should know), `docs/decision-log.md` (why
we pivoted), `docs/automation-runbook.md` (how *this* project's lanes are driven). Those are BFM's
history. **This file is the part that transfers.**

The rule for what belongs here: *if it would still be true for a PS2 game built with a different
compiler, it goes here. If it is a fact about gcc-2.7.2 or about Brave Fencer Musashi, it does not.*

---

## 0. What the system assumes

1. **A byte-exact target exists** — an original binary you must reproduce exactly.
2. **A build you control** that can, in principle, reproduce it (right compiler, right flags, right
   linker order). Establishing that triple is prerequisite work, not part of this system.
3. **A splitter/disassembler** that emits per-function assembly and a config describing the layout
   (splat, or an equivalent). The system needs to address one function at a time.
4. **Cheap parallel model capacity.** Not necessarily frontier models — see §7.

Everything below is about what you do *after* those four exist, which is where the years go.

---

## 1. The one non-negotiable: the byte gate

**A function is done when the whole binary still hashes correctly with that function compiled from
source. Nothing else counts.** Not "looks equivalent", not a passing test, not a local diff of zero.

Every other signal in the system is a *filter* feeding this gate, and each one is blind to something:

| oracle | what it proves | what it is blind to |
|---|---|---|
| local per-function compile + masked diff | instruction SHAPE matches | symbol identity (relocations are masked), declarations in the real TU, optimization level |
| symbol-identity check | the draft names the symbols the target actually references | whether the body is right |
| **whole-binary rebuild + hash** | **everything** | nothing — this is the arbiter |

Two failure modes this table exists to prevent, both observed:

* **A clean local MATCH that cannot link**, because the draft named a symbol that does not exist.
  The local oracle masked the relocation, so it scored zero diff.
* **A local mismatch on every instruction** because the local oracle compiled at the wrong
  optimization level. The feedback could never converge, and nothing in the diff said why.

**Design rule:** every oracle must state what it cannot see, in its own output. An oracle that
answers confidently outside its competence is worse than no oracle.

---

## 2. Lanes: separate what has different clocks

The naive design is one loop: pick a function, draft it, verify it, repeat. It fails at scale because
the steps have *different natural rates and different failure modes*. Split them into independent,
restartable lanes:

| lane | rate | may it stop? |
|---|---|---|
| **drafter** | bounded by model capacity and by how many work items you can produce | **never stop it to ship a change** — it is usually the clock-limited resource |
| **gater** | bounded by build time | freely restartable; nothing is lost but a pause |
| **maintenance** | opportunistic, zero-cost mechanical work (see §5) | freely |
| **watchdog** | fixed short interval | freely |
| **distiller** | slow, human-paced | freely |
| **second population** | its own clock (see §6) | freely |

**The single most expensive mistake we made in this area:** stopping the drafting lane to ship a code
change. It cost 139 of 162 idle minutes in one session. Ship changes at a wave boundary, or to a lane
that is not the clock-limited one.

**An implementation trap worth stating because it is invisible:** a shell parses a `while … done`
body *in full* before running it, so editing the lane script does not change the running loop, and
restarting only the inner process re-runs the *old* arguments. Know, for your runtime, which of
{code, arguments, per-invocation defaults} takes effect when. Verify from the process, not the file.

---

## 3. The card: fuel, not a ticket

The unit of work handed to a model is not "function X, go". It is a **card**: everything the project
already knows that bears on this function, assembled deterministically at zero token cost.

What earned its place on ours, each measured:

* the target's disassembly path and its destination source file;
* **an already-matched sibling** with the same skeleton, when one exists (this single field moved a
  wave from 0 banked to 51 banked);
* **what the destination file already declares** — a drafter that invents a signature the file
  contradicts produces a body that compiles alone and not in place;
* **the project-wide declaration consensus** for each callee, because the assembly frequently cannot
  tell you a function's arity and the corpus can;
* **the lever**: which known pattern this function is believed to exhibit — *plus what that lever
  means and where to read about it.*

**The lever lesson generalizes hard.** We labelled cards with lever names that appeared **nowhere in
our own knowledge base**. 108 model transcripts show the agent dutifully searching for the exact
word on its card and finding nothing. A label a worker cannot look up is not fuel; it is a dead end
that costs a search and buys nothing. **If you put a name on a card, that name must resolve in your
knowledge base by the words on the card.**

---

## 4. Refuse work the pipeline cannot bank

The most damaging bug class in this system is not a crash. It is **a true number about a narrower
scope than the reader assumes** — a step that quietly skips, or quietly accepts, work it cannot
handle, so the failure looks ordinary and gets attributed to the worker.

Four instances, all real, all costly:

1. Functions compiled at a different optimization level than their object was drawn as cards **79
   times across 19 waves**. None could ever have banked. Every failure looked like a model failure.
2. The batch gater accepted a binary class it structurally could not gate: **105 cards, 0 banked**,
   while the same wave's other 115 cards banked 94. The whole wave read as a drafting collapse.
3. A tool reported "12 banked of 12" because it compared function *names* against a set keyed by
   *address* — always true, therefore always "banked".
4. A draw refused **the entire wave** whenever any binary was mid-gate, silently falling back to
   pre-drawn waves — so every new draw-time feature stopped reaching the fleet while the logs showed
   healthy activity.

**The rules that fall out of these, stated portably:**

* **Draw-time bankability.** Never hand out work the pipeline cannot bank. Filter at the source, and
  *count what you filtered* in a visible census.
* **Refuse loudly, never mishandle.** A tool that cannot process an input must say so and name the
  tool that can — silently producing a plausible failure is worse than skipping.
* **Assert the denominator.** Every rate ships with what it is a fraction of. A metric derived from
  an invariant beats one that re-parses the world.
* **Scope a refusal to what is actually unsafe.** A blanket guard that fires constantly gets routed
  around, and the workaround becomes the silent failure.

---

## 5. Free work before paid work

Every project has mechanical work that costs no model tokens: the same function appearing in several
binaries, a proven body remappable to a sibling, a deterministic transformation of an already-banked
result. **Run it in its own lane, opportunistically, whenever the paid lane is idle.**

Corollary for the card draw: if two work items are the *same* item, draft one and derive the other.
Ours collapses same-skeleton members to one card and defers the siblings to a free remap — drafting
both pays twice for something a script gives away.

---

## 6. Populations have different clocks — give each its own lane

Not all of the target is the same kind of work. Ours splits into: many small independent overlay
binaries (fast gate, cheap), and one large executable (slow gate, must rebuild wholly, bisects on
failure).

The large one had been excluded from the main loop for a good reason — its gate is expensive and
stalled everything behind it — and the consequence was that **it got no attention at all**, while
the fast loop ran at a quarter of the available model capacity because it could not produce work
items fast enough. Two populations, one idle half of a rate limit.

**Rule: an excluded population needs its own lane, not an exclusion.** Give it a cadence matched to
its own gate cost, and let the two lanes share the capacity.

Batching is what makes an expensive gate affordable: one rebuild verifies N drafts. Two conditions
make batching work — a *pre-filter* strong enough that most of the batch is right, and a *bisect*
when it is not. And measure the gate before you fear it: ours was believed to cost 40-60 minutes and
actually costs ~15 seconds when the batch is clean. The stalls were bisects, not rebuilds.

---

## 7. Model routing and budgets

* **Route by difficulty, and measure the cliff.** Ours: cheapest tier ≤30 instructions, mid tier to
  ~120, strongest above. Measured, not assumed — the cheap tier's success drops from 86% to 20%
  across that range, and the earlier hand-waved boundary was wrong by a factor of two.
* **Budget per lane, not per project.** A turn/cost cap that fits a small function starves a large
  one: 98 of 270 attempts on our hardest population ended *at* the cap rather than at a wall.
* **Reserve the strongest model for genuinely new walls** — an unsolved tooling problem, an
  adversarial review of a design, a residual no documented lever reaches. Reviewing a pile of
  artifacts against an existing knowledge base is mid-tier work, not frontier work.
* **Cheap tiers are honest.** Across 100 workers, 63 claimed matches were 63 real matches. Treat
  their verdicts as a reliable *filter* and never as the gate.

---

## 8. The flywheel: harvest, distil, and the one-wave lag

Workers discover things. If discoveries do not reach the *next* workers, you re-buy the same lesson
forever.

```
gate accepts a function → harvest the worker's note (only for BYTE-PROVEN results)
   → distil into the knowledge base (human + a mid-tier reviewer)
      → the next workers grep it on their next card
```

Four things we learned the hard way:

1. **Harvest only from proven results.** A note attached to an unverified draft is a lesson about a
   function you did not reproduce.
2. **Extraction is not distillation.** Ours harvested automatically and correctly for weeks while the
   ore piled up unread; only what reaches the knowledge base changes behaviour.
3. **Expect ~85% of harvested claims to be already covered.** That is not waste — a fast correct
   "already known, see §N" is most of the value, and it stops the base bloating with duplicates.
4. **One in three credited levers is inert.** Workers stack edits; when the match closes, the
   last-added edit gets the credit, and byte-inert riders *survive into the accepted result precisely
   because they are inert*, which then reads as proof. **Before a lever enters the knowledge base,
   strip it from the accepted body and recompile.** Measured twice: 4 of 8, then 6 of 19.

**Accept the one-wave lag.** Wave N's lessons land while wave N+1 is already in flight, so wave N+2
is the first that can use them. The alternative — pausing production to think — costs more than the
lag does.

---

## 9. The economics, as measured

Numbers from BFM, stated so another project can calibrate rather than copy:

| quantity | measured |
|---|---|
| drafts → banked, fleet-wide | **34%** (8,885 drafts → 3,027 banked over 37 waves) |
| bank rate by function size | ~57% under 50 instructions · ~30% at 50-80 · ~22% at 80-120 · ~3% at 120-200 · ~6% above |
| bank rate by population | the "hard" population banks 27-40% at small sizes — **the gap to the easy population was almost entirely SIZE MIX, not difficulty** |
| provider rate ceiling | rejections stay ~0-3.5% up to ~95 req/min; 6.6-12.7% at 195-227; retries absorb it |
| per-worker request rate | 0.3-0.8 req/min, so ~350-400 concurrent workers sits at the knee |
| throughput | ~2,000 functions banked per day, unattended, at a marginal model cost of roughly zero on a free tier |

**The single most useful economic fact:** *card supply*, not model capacity, was the binding
constraint for most of the campaign. We repeatedly reached for more workers when the answer was more
work items — and once a second population got its own lane, capacity stopped being the question.

---

## 10. What transfers, and what does not

**Transfers:** everything above — the gate discipline, the oracle ladder, lanes, cards, draw-time
refusal, free-before-paid, per-population clocks, model routing, the flywheel and its inert-rider
law, and the economics *shape* (not the constants).

**Does not transfer:** the compiler idioms themselves. Our knowledge base is ~780 sections of
gcc-2.7.2 behaviour; another target needs its own, built the same way. **The knowledge base is
per-compiler; the machine that builds it is universal.** That is the whole thesis of this document:
a new project inherits the *system* on day one and spends its effort discovering its own compiler's
idioms rather than rediscovering how to run a decomp.

---

## 11. Bootstrapping order for a new project

1. Establish the byte-exact build triple and a whole-binary hash check. Nothing else matters until
   the hash can go green on an all-assembly build.
2. Stand up the local per-function oracle **and make it state its blind spots** (§1).
3. Build the card: destination file, existing declarations, project-wide consensus, any sibling.
4. Run a *small* manual wave. Measure bank rate by size. You now have your routing cliff (§7).
5. Add the byte gate as a lane, with a per-binary lock so gates can run in parallel.
6. Turn on harvesting from proven results only. Distil the first batch by hand — you are writing the
   seed of your knowledge base, and its *vocabulary* decides whether anyone finds it later (§3).
7. Only now scale the worker count, and watch the rejection rate bucketed over time rather than at
   launch (launch bursts fake a ceiling).
8. Give every excluded population a lane before you give the main loop more workers (§6).