mirror/BFM-decomp
1
0
Fork 0
mirror of https://github.com/Druthulu/BFM-decomp synced 2026-09-26 13:33:34 -04:00
Code Issues Packages Projects Releases Wiki Activity

feat(claude_wave_packs): wire neighbor_ref into every pack, and resolve its names to the source spelling

Browse Source 
playbook §2b has called neighbor_ref the biggest measured cost lever in the
wave since S68 (~20x token swing) and documented it as a MANUAL per-card
command wired into nothing — so it ran for approximately zero cards. Packs now
carry an ALREADY-MATCHED NEIGHBOURS block, same additive never-fail contract as
the past-attempt notes. First run: 30/30 targets had a matched neighbour.

It also shipped with a defect that would have silently un-done it:
neighbor_ref reports the SYMBOL-TABLE name, and for an unnamed function that is
Ghidra's FUN_8003a0e4 — which appears nowhere in src/*.c, where the function is
func_8003A0E4. An agent sent to read FUN_8003a0e4 finds nothing and concludes
there is no neighbour. _src_name resolves against the destination TU's own text,
falls back to the address, and shows the symbol-table spelling in parentheses.
Measured: 150 of 150 neighbour names needed resolving; 0 primary names remain
Ghidra-style. Checked against known-true cases first (resolves FUN_8003a0e4,
leaves func_8003A0E4 alone, leaves an unknown name untouched).

R61(b): the pack was asserting a name true of the symbol table and false of the
world the agent works in.
This commit is contained in:
Drew T
2026-09-03 20:08:27 -06:00
parent e059f85298
commit f9f446449e
2 changed files with 107 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/wave-playbook.md
+24 -1
View File
@@ -217,7 +217,30 @@ crack ONE exemplar -> gate -> BANK -> re-run seed_ref/--near for the rest of the
**And never draft two members of the same cluster in parallel** — if either cracks, the other is
free, so the second agent is pure waste (§397).
### 2b. RUN `neighbor_ref` FOR EVERY CARD — the biggest measured cost lever in the wave
### 2b. WORKED-EXAMPLE NEIGHBOURS — **AUTOMATIC SINCE S77**; read the coverage line
```
worked-example neighbours: 30/30 target(s) have a matched neighbour; appended to 30 pack(s)
```
`claude_wave_packs.py` now calls `neighbor_ref.neighbors()` for every target and appends an
**ALREADY-MATCHED NEIGHBOURS — READ THESE FIRST** block to its pack, exactly like the past-attempt
notes in §3b. Additive and never fails a wave.
> **Why this changed (P31 S77).** From S68 to S77 this step was documented as a MANUAL per-card
> command and wired into nothing — so on a 30-card wave it ran for approximately zero cards, while
> the playbook called it the biggest measured cost lever in the wave. A lever the pack does not
> carry is a lever nobody pulls. First automatic run: **30/30 targets had a matched neighbour.**
>
> **And it shipped with a name bug that would have silently un-done it.** `neighbor_ref` reports the
> SYMBOL-TABLE name, which for an unnamed function is Ghidra's `FUN_8003a0e4` — a string that
> appears NOWHERE in `src/*.c`, where that function is `func_8003A0E4`. An agent told to read
> `FUN_8003a0e4` greps, finds nothing, and concludes there is no neighbour. The pack renderer now
> resolves every name against the destination TU's own text and falls back to the address; the
> symbol-table spelling is shown in parentheses. Measured on the first wave: **150 of 150 neighbour
> names needed resolving.**
Run it by hand only when you want the ranking outside a wave:
```
python3 tools/neighbor_ref.py --binary <bin> --fn <fn> --top 5
tools/claude_wave_packs.py
+83
View File
@@ -144,6 +144,60 @@ def _residual_block(t, where):
"Note:" if j.get('nins') else "", rows, more, _index_bucket(klass)))
_NEIGHBOR_HEADING = "## ALREADY-MATCHED NEIGHBOURS — READ THESE FIRST"
def _src_name(tu_path, name, addr):
"""The neighbour's name AS THE SOURCE SPELLS IT (P31 S77).
`neighbor_ref` reports the symbol-table name, which for an unnamed function is Ghidra's
`FUN_8003a0e4` — and that string appears NOWHERE in src/*.c, where the same function is
`func_8003A0E4`. A pack that tells an agent to read `FUN_8003a0e4` sends it to grep for a name
that does not exist, it finds nothing, and it concludes there is no neighbour — silently
defeating the ~20x lever this block exists to supply. Resolve against the TU text and fall back
to the address, which is never ambiguous. (R61: the pack asserted a name true of the symbol
table and false of the world the agent works in.)"""
try:
txt = open(tu_path, errors='replace').read()
except OSError:
return name
if name and name in txt:
return name
try:
cand = "func_%08X" % int(str(addr), 16)
except (TypeError, ValueError):
return name
return cand if cand in txt else name
def _render_neighbors(r):
"""The ranked worked examples, as pack markdown. SAME-TU first because it shares the decl
environment and the carve, and its header comment usually records the levers it needed."""
L = ["\n\n" + _NEIGHBOR_HEADING, ""]
L.append("A neighbour is a WORKED EXAMPLE TO READ, never a body to copy — cousin-remap measured "
"0/26 (§168 law 1). SAME-TU beats everything; an opt-level mismatch actively misleads "
"(an -O2 example against an -O0 target, §116).")
L.append("")
L.append("TU `%s` — %d matched function(s) in it, %d in the binary.%s"
% (r.get("tu"), r.get("matched_in_tu", 0), r.get("matched_in_binary", 0),
" **THIS TARGET IS -O0.**" if r.get("o0") else ""))
for n in r["neighbors"]:
L.append("")
_nm = _src_name(r.get("tu"), n["name"], n["addr"])
L.append("* **%s** @ %s — %d ins, score %s%s%s"
% (_nm, n["addr"], n["nins"], n["score"],
" **<< SAME TU**" if n["same_tu"] else "",
(" (symbol table calls it `%s`)" % n["name"]) if _nm != n["name"] else ""))
L.append(" * why: %s" % "; ".join(n["why"]))
if n.get("header"):
L.append(" * its header comment (often names the levers it needed):")
L.append(" ```")
for line in n["header"].splitlines():
L.append(" " + line)
L.append(" ```")
return "\n".join(L) + "\n"
def main():
global A_NO_RESIDUAL
if len(sys.argv) < 3:
@@ -216,6 +270,35 @@ def main():
except Exception as _e: # fuel is additive — never fail a wave over it
print('past-attempt notes SKIPPED: %s: %s' % (type(_e).__name__, _e))
# WORKED-EXAMPLE FUEL (P31 S77, playbook §2b). `neighbor_ref` answers the question that is
# weaker than seed_ref's "is there a byte-identical twin?" and FAR more often answerable:
# "which already-MATCHED function should this agent READ first?". S68 measured a ~20x token
# swing on exactly that variable — every cheap large match came from an agent finding a matched
# neighbour, and the ones with none cost 200-350k each. It has been a MANUAL per-card step in
# the playbook ever since, wired into nothing, so in practice it ran for approximately no cards.
# A lever the pack does not carry is a lever nobody pulls (§478's shape: enumerate the
# consumers). Same additive, never-fail-the-wave contract as the past-attempt notes above.
try:
import neighbor_ref as _nr
_nhit = _nadd = 0
for _t in targets:
_fn = _t.get('name') or _t.get('fn')
_p = os.path.join(out, "packs", "%s.md" % _fn)
if not os.path.exists(_p):
continue
_r = _nr.neighbors(_t.get('binary'), _fn, 5)
if _r.get('error') or not _r.get('neighbors'):
continue
_nhit += 1
if _NEIGHBOR_HEADING in open(_p, errors='replace').read():
continue
open(_p, 'a').write(_render_neighbors(_r))
_nadd += 1
print('worked-example neighbours: %d/%d target(s) have a matched neighbour; appended to %d pack(s)'
% (_nhit, len(targets), _nadd))
except Exception as _e: # fuel is additive — never fail a wave over it
print('worked-example neighbours SKIPPED: %s: %s' % (type(_e).__name__, _e))
print('packs: %d written to %s' % (n, out))
print('cards: %d/%d matched on (binary, fn); %d target(s) have a same-named card in ANOTHER binary '
'(DROPPED, not substituted — R48); %d card(s) skipped for carrying no binary'