perf: cut analysis hot-path overhead without changing output

[r0ny123]

Summary

Six focused changes that cut measurable overhead from the analysis pipeline, plus a follow-up commit fixing two defects that self-review found in two of them.

Commit	What it does	Indicative effect
hoist per-instruction lookups out of analyzeFunction	binds code_map/data_map/ins2fn/buffer/bound methods to locals in the instruction loop (~180k attribute chains per 29k-instruction sample); containers are only mutated in place, so aliasing is safe	~1-3% end-to-end
reuse escape results + skip redundant report-build work	PIC-hash escaping memoized behind a size-capped cache keyed on the complete input tuple of escapeBinary; getNormalizedBlockRefs fast path for functions without try_ranges; drop a duplicate fix_graph() in the nesting-depth pass	real binaries repeat 30-50% of instructions (98% in a DEX classes dump)
prefilter AArch64 candidate scans by top byte	BL encodings have top byte 0x94-0x97 and prologues {0xA9, 0xD5, 0xF8} - verified exhaustively over each pattern's free bits - so one bytes.translate over the top-byte lane skips non-matching words at C speed; full per-hit verification kept, timeout polling boundaries unchanged	prologue scan 4.14ms -> 0.74ms, BL 1.17ms -> 0.59ms; scans are O(image bytes), so large ARM64 dumps save proportionally more
trust the block queue as the emptiness signal	hasUnprocessedBlocks() allocated a set difference on every call although the queue and processed sets are disjoint by construction; O(blocks^2) allocation on wide functions	removes the quadratic trap
hoist Dalvik resolver closure	one resolver closure per analysis pass instead of one per decoded instruction (~9.8k allocations avoided)	small but free
defer ApiScout DB parsing to first API lookup	uncached databases cost ~26ms at backend construction even when no API is ever resolved; cached ones still attach eagerly so os-name selection stays cheap	cold-start only when API files are configured

Every change was benchmarked before and after, and full serialized reports hash byte-for-byte equal to master across ten bundled fixtures covering all four backends (intel x86/x86-64 memory dumps, aarch64 static + Mach-O, dalvik DEX classes, CIL), with volatile fields (timestamp, execution_time) excluded from the comparison.

Interleaved median wall-clock vs master on this machine: aarch64_static -9 to -10%, komplex -6 to -7%, blockblast/asprox -2 to -4%, cutwail/njrat neutral within noise.

Follow-up fixes

Self-review of the six commits above found two defects. Both live on paths that no bundled fixture reaches, which is exactly why the report-identity check could not see either one: neither can move a fixture hash. Both are fixed in the final commit, each with a regression test that fails on the pre-fix source.

An explicit ApiScout OS name was silently discarded. Deferring database parsing moved the os-name inference out of WinApiResolver.__init__ and into the first getApi() call, where it ran unconditionally and overwrote a name an intervening setOsName() had pinned. Before the deferral, the inference could only run while no caller had yet had the chance to set one, so the setter always won. It now returns early when a name is already set, matching Disassembler._ensureHashes, which fills only fields that are still unset. _deferred_dbs is initialized on both construction paths as well, so reading it needs no getattr fallback and the non-deferred path no longer raises AttributeError.

The getNormalizedBlockRefs() fast path stopped normalizing. It returned each successor list unchanged, on the grounds that getBlockRefs() already emits them sorted and deduplicated. That holds for analysis-produced data, but the same method is also the normalizer on the fromDict() path, where blockrefs come from a report this code did not necessarily write; there it became a no-op, and duplicates reached the SCC and dominator-tree passes. Restoring sorted(set(...)) keeps what the fast path actually saves - it still skips the per-block try-range overlap test and the intermediate dict - and it stays 1.85x faster than the slow path it bypasses, measured interleaved over 319 functions harvested from two bundled fixtures. Equivalence with the slow path was then re-checked over 3000 randomized inputs, including blockrefs carrying keys absent from blocks: values, key set and key order all match.

A whole-tree sweep for each root-cause signature found no further sites in src/smda/.

A third defect, and what it says about the validation above

The report-identity check missed a third defect, and this one is worse than the two above: the path was not unreached, it was under-represented. perf(common): drop redundant ref bookkeeping and speed hot lookups re-keyed updateFunctionGaps() from a walk over code_map byte keys to merging the instruction intervals of disassembly.functions, leaving the byte walk reachable only when functions is empty.

The two are not interchangeable. code_map records every decoded byte; disassembly.functions records only finalized functions. Deriving gaps from the latter drops the decoded-but-unattributed regions out of the gap scan, and with them every candidate the scan would have seeded there. On a 32-bit MSVC PE cross-compiled from Rust (hyperfine 1.19.0, i686-pc-windows-msvc), recovery falls from 6249 functions to 5247 - a loss of 1002, or 16%. Measured revision by revision across this branch, everything before that commit reports 6249 and everything after reports 5247.

The rewrite did not pay for itself either. updateFunctionGaps() runs once per analysis, and the interval merge costs more than the byte walk it replaced: 0.0410s against 0.0365s cumulative under cProfile. Reverting restores 6249 at unchanged wall-clock, so the speedups claimed above are unaffected.

Only that hunk is reverted. The rest of the commit keeps its wins - the _passesCodeFilter bisect index, the candidate-queue update, the reference-pair bookkeeping removal, and the SmdaInstruction.from_tuple and getOutRefs work are untouched.

The same commit also added test_interior_holes_match_the_covered_byte_walk, which passed an empty code_map and asserted a gap length derived from function intervals - pinning the new behaviour under a name describing the old contract, so the suite could not object to it. It now exercises code_map, and a second test asserts that gaps follow code_map coverage when both sources are populated; that test fails on the pre-revert source.

None of the ten bundled fixtures is gap-dominated, which is why a 16% recall loss could not move a single hash. The lesson from the two defects above generalizes further than it was first written: a report-identity comparison is evidence about the fixtures, not about the change, and it is only ever as strong as the fixtures are representative.

Changed behavior

Reports serialize identically on all fixtures listed above, and the golden corpus expectations are untouched. That statement is about the fixtures and not about every binary: as described in the section above, one commit did change recovery on a 32-bit MSVC PE outside the fixture set, and the revert restores it. Three behavioral nuances are intentional. An uncached ApiScout database is now parsed at the first getApi() call rather than at resolver construction, so the missing-file log timing moves with it. An explicit setOsName() outranks the os-name inference regardless of when the deferred load fires, restoring the pre-deferral ordering. And getNormalizedBlockRefs() still deduplicates and sorts successor lists on the fromDict() path, as it did before the fast path was introduced.

Approaches that were tried and rejected after measurement, for the record: enlarging Capstone disassembly windows (slower despite fewer calls - object construction dominates), batch-decoding instruction details for string extraction (slower for the same reason), fusing the intel candidate-scan regexes (measured 1.0x), interval-backed processed_bytes (no gain).

Validation

• python -m pytest tests/ : 1847 passed, 1 skipped, 2584 subtests
• make lint and ruff format --check .: clean
• make typecheck: exit 0, diagnostic count unchanged against the same tree without these changes
• Report-identity hashes (serialized toDict() SHA256, volatile fields scrubbed) equal to master across 10 fixtures spanning intel/aarch64/dalvik/cil, default config and WITH_STRINGS=True
• Function recovery on the 32-bit MSVC PE described above: 5247 -> 6249, status: ok, analysis ~1.8s
• Diff coverage against the base branch: 99% overall, 100% on the lines changed by the revert. The two uncovered lines are the residual per-hit verification arms of the AArch64 top-byte prefilter (a word whose top byte matches but whose full encoding does not, and a prologue rejected by the code filter); neither is reached by a bundled fixture today.

[r0ny123]

Pushed f8c3e57, which fixes two defects that self-review found in the earlier commits on this branch. Body updated with the details; the numbers below are the final ones for the branch as it now stands.

Neither defect could move a fixture hash, so the report-identity check the earlier commits rest on could not see either. setOsName() is never called anywhere in the analysis pipeline, and the blockrefs divergence needs input that this code does not itself produce — it only surfaces on the fromDict() path.

Reproductions, before and after the fix

Explicit OS name, with two configured ApiScout databases where one file is missing:

before  os_name='good'     getApi(0x70001000) -> ('good.dll', 'GoodApi')
after   os_name='absent'   getApi(0x70001000) -> (None, None)      # matches master

Blockrefs normalization, blockrefs = {0x10: [0x20, 0x20, 0x08]}:

before  {16: [32, 32, 8]}
after   {16: [8, 32]}                                              # matches master

Validation

Gate	Result
full test suite	1817 passed, 1 skipped, exit 0
lint and format check	clean
typecheck	exit 0, diagnostic count identical to the same tree without these changes
both new tests against the pre-fix source	2 failed — the tests are non-vacuous
fast-path vs slow-path equivalence, 3000 randomized inputs	0 mismatches in values, key set and key order
whole-tree sweep, both root-cause signatures	clean, 0 siblings outstanding
diff coverage vs base	98% overall, 100% on both files this commit touches

Performance impact of the fix

Restoring sorted(set(...)) gives back part of the fast path's saving but keeps most of it. Measured interleaved in one process over 319 functions (2545 blocks, 3342 edges) harvested from komplex and asprox:

slow path (master)              0.68 ms   1.00x
fast path, list()               0.20 ms   0.30x
fast path, sorted(set())        0.37 ms   0.54x

The absolute difference between the two fast-path variants is 0.17 ms across an entire report, against multi-second analyses, and getNormalizedBlockRefs() is memoized per function. This line was never load-bearing for the headline numbers in either direction.

The two uncovered diff lines are in the AArch64 top-byte prefilter from an earlier commit, not in this one: the arm taken when a word's top byte matches but its full encoding does not, and a prologue rejected by the code filter. Both are genuine residual-verification paths that no bundled fixture reaches. Happy to add coverage for them if you would prefer the gate at 100%.

[r0ny123]

Pushed 999fe74, which reverts one hunk of perf(common): drop redundant ref bookkeeping and speed hot lookups and adds the regression tests for it. The PR body now carries the detail; the short version and the numbers are here.

That commit re-keyed updateFunctionGaps() from a walk over code_map byte keys to merging the instruction intervals of disassembly.functions. code_map records every decoded byte and disassembly.functions only finalized functions, so the new source silently drops decoded-but-unattributed regions out of the gap scan along with every candidate the scan would have seeded there.

Measured on a 32-bit MSVC PE cross-compiled from Rust (hyperfine 1.19.0, i686-pc-windows-msvc), disassembled with each revision of this branch in turn:

revision	functions	status
every revision before the commit	6249	ok
the commit, and every revision after it	5247	ok
after 999fe74	6249	ok

That is 1002 functions, or 16%. The rewrite was also not faster: updateFunctionGaps() runs once per analysis, and the interval merge costs 0.0410s cumulative under cProfile against 0.0365s for the byte walk it replaced, so the revert restores recovery at unchanged wall-clock and none of the speedups this PR claims are affected. Only that hunk is reverted; the _passesCodeFilter bisect index, the candidate-queue update, the reference-pair bookkeeping removal and the SmdaInstruction.from_tuple and getOutRefs work are untouched.

Worth flagging separately: the same commit added test_interior_holes_match_the_covered_byte_walk, which passed an empty code_map and asserted a gap length derived from function intervals. It pinned the new behaviour under a name describing the old contract, so the suite could not object. It now exercises code_map, and the added test_gaps_follow_code_map_coverage_not_recovered_function_extents asserts that gaps follow code_map coverage when both sources are populated; it fails on the pre-revert source.

This is the third defect the report-identity check did not catch, and the first that is not explained by an unreached path. None of the ten bundled fixtures is gap-dominated, so a 16% recall loss could not move a single hash.

Validation on the pushed head: the full suite reports 1847 passed, 1 skipped and 2584 subtests; lint and format checks are clean; the type checker exits 0 with no error-level diagnostics; and diff coverage against the base is 99% overall with 100% on the lines changed by the revert.

[danielplohmann]

Same pass as #300 (comment), and this one inherits that PR's position because it contains it — the branch carries #300's 456b855 plus sixteen of its own perf and fix commits on top.

Cleared: fuzz_buffer was infra, not a hang

Yesterday's open question on this PR was whether the fuzz_buffer job failing at 55 minutes against a timeout-minutes: 45 cap was an infra timeout or a hang the perf changes introduced. The logs had expired, so it needed a re-run to tell those apart.

It has since re-run green: Fuzz (fuzz_buffer) passes in 2m45s, along with all five other fuzz targets. Nothing here hangs. That item is closed and does not need to come back.

The rest is blocked behind #300

Both of this PR's problems are #300's problems, arriving one layer down:

• The rebase. The branch carries pre-squash copies of fix(ci): address ty 0.0.74 unsound-return checks #302, fix(intel): keep the switch index tied across a relative dispatch's base add #306, fix(aarch64): stop recording a branch target as an inbound call reference #307, docs(docs): say which address space a report's offsets are in #308, perf(intel): refuse gap candidates the exception directory places inside a function #309 and fix(aarch64): read the BTI target type, and resume past a refused pad's block #310, and feat(core): function-boundary accuracy from what the image declares #300's commit underneath its own. Rebasing feat(core): function-boundary accuracy from what the image declares #300 first is the natural order; this then reduces to its sixteen.

• The validation basis. The headline claim here is report-identity: "full serialized reports hash byte-for-byte equal to master across ten bundled fixtures." That was true against the master it was measured on. Since then perf(intel): cut on padding that falls through, not only on padding after a call #304, fix(aarch64): stop recording a branch target as an inbound call reference #307, perf(intel): refuse gap candidates the exception directory places inside a function #309, fix(aarch64): read the BTI target type, and resume past a refused pad's block #310, fix(aarch64): candidate-quality follow-ups to the BTI landing-pad series #311 and perf(aarch64): refuse a gap candidate the ARM64 PE unwind data places inside a routine #312 have all changed recovery output on bundled fixtures — I scored the v4.5.0 → current delta this morning and eight of the twenty-one fixtures these paths reach now move, including rust_pe_gnu_xored (2,355 → 2,201 starts) and five of the eleven ARM64 Mach-O cells. So the ten report hashes need regenerating against current master before "byte-for-byte equal" means anything again.

  That is a mechanical re-run rather than a re-think, and it is the right check for this PR — a perf change that claims to alter nothing is exactly the case where an identity hash is the correct gate. It just has to be an identity hash against the tree it will land on.

What I have read so far, and liked

I have not reviewed the diff line by line yet, for the same reason as #300 — it is not readable until rebased. But the PR body is, and two things in it are worth saying out loud now rather than at merge time.

The third defect writeup is the most useful thing in either PR. Finding that updateFunctionGaps() had been re-keyed from code_map to disassembly.functions, that this silently dropped decoded-but-unattributed regions out of the gap scan, that it cost 1,002 functions (16%) on a 32-bit MSVC PE, and that no bundled fixture is gap-dominated enough to notice — and then reverting only that hunk while keeping the rest of the commit's wins — is a better outcome than the change never having been made. The generalisation you drew is the right one and I would like it on the record beyond this PR: a report-identity comparison is evidence about the fixtures, not about the change. That is precisely the failure mode that let it through, and it is the same shape as the two figures we shipped in v4.5.1 marked as unverifiable because no bundled fixture reaches them (#322).

Pinning a new behaviour under a name describing the old contract — test_interior_holes_match_the_covered_byte_walk passing an empty code_map and asserting a gap length derived from function intervals — is the sharpest single example of a test that cannot fail I have seen in this repo. Worth keeping the corrected version's docstring explicit about why it now populates both sources.

Also noting for the record that you list the approaches you measured and rejected — larger capstone windows, batch detail decoding, fused candidate regexes, interval-backed processed_bytes. That saves the next person from re-deriving four dead ends, and it is unusual to bother writing down.

Order of operations

1. feat(core): function-boundary accuracy from what the image declares #300 rebases onto current master and re-measures.
2. This rebases on top and regenerates the ten report hashes against the same tree.
3. Then I review both properly.

No urgency — neither is going into v4.5.1, and we are travelling shortly. Better measured than fast.

[r0ny123]

Rebased, in the order you asked for: #300 first onto 6240b74, then this on top of it.

What is in it now

Twenty-one commits — #300's three plus the test-repair commit its rebase needed, then the sixteen of this branch's own, then one more: the docstring you asked for on test_interior_holes_match_the_covered_byte_walk. The pre-squash copies of #302, #306, #307, #308, #309 and #310 are gone, including the two on this branch that were #310's series (resume past a refused landing pad's block and stop the refused-pad walk at a trap); master carries both as 7d01480.

Four of the sixteen needed real resolution rather than a textual merge:

• perf(aarch64): prefilter candidate word scans by instruction top byte — the chunked prefilter loop now wraps the current bodies of the bl reference scan and the prologue scan, so it keeps fix(aarch64): stop recording a branch target as an inbound call reference #307's self._call_targets.add(target) and fix(aarch64): read the BTI target type, and resume past a refused pad's block #310's _isLikelyInteriorBtiCandidate(addr, word) signature rather than the pre-fix(aarch64): stop recording a branch target as an inbound call reference #307 shapes it was written against.
• perf(common): drop redundant ref bookkeeping and speed hot lookups — SmdaInstruction.from_tuple goes in, but getDataRefs keeps master's typed body from refactor(common): type the attributes the dropped annotations rest on #320 (-> Iterator[int], direct self._data_refs) rather than reintroducing the getattr that the annotation work removed.
• perf(aarch64): skip non-matching words and capstone data-ref decodes — both sides of the test-file conflict were additive, kept both.
• fix(common): restore code_map as the gap-scan coverage source applies unchanged on top.

The report hashes, regenerated against the tree this lands on

You are right that the old claim had gone stale, and for the reason you named rather than for a rebase reason. Regenerated:

Ten bundled fixtures, computeReportIdentityHash over the full serialized report, timestamp and execution_time excluded. Three trees: current master 6240b74, #300 rebased onto it, and this branch rebased onto that.

fixture	backend	master 6240b74	#300 rebased	this branch
asprox	intel	d961211b	d961211b	d961211b
cutwail	intel	e201853a	e201853a	e201853a
bashlite	intel	be88d8f5	be88d8f5	be88d8f5
blockblast	dalvik	767ebb8e	767ebb8e	767ebb8e
komplex	intel	7fce68c9	7fce68c9	7fce68c9
njrat	cil	cc2a2ea3	cc2a2ea3	cc2a2ea3
pe_export	intel	6d4b219a	6d4b219a	6d4b219a
aarch64_static	aarch64	1f415f37	3613e186	3613e186
aarch64_switch_macho_O0	aarch64	418c8419	418c8419	418c8419
dotnet_readytorun	intel	713c981f	9c651848	9c651848

This branch is byte-for-byte equal to the tree it lands on, on all ten. That is the claim the PR makes and it is now made against the right baseline rather than against v4.5.0.

The two that move do so between master and #300, not here: aarch64_static 278 → 276 functions and dotnet_readytorun 419 → 626, both #300's business and both explained over there.

And with your point taken about what this proves: it proves these sixteen commits change nothing on these ten images. It is not evidence about updateFunctionGaps, because none of the ten is gap-dominated — which is the whole reason 3ff05a8 exists. The gap-scan behaviour is pinned by test_gaps_follow_code_map_coverage_not_recovered_function_extents, which fails on the pre-revert source, rather than by any hash.

fuzz_buffer

Noted, and thanks for re-running it rather than leaving it as an open question on the branch. Nothing here holds a lock or loops on buffer content, so I had no better explanation than "infra" either — good to have it settled by a green run rather than by argument.

On the third defect

Taking the generalisation as a standing rule rather than a one-off, since you asked for it on the record: a report-identity comparison is evidence about the fixtures, not about the change. Concretely: an identity hash is a gate only for paths a fixture actually reaches. Everywhere else it reports coverage and reads as behaviour, which is exactly how the 16% gap-scan recall loss got through — none of the ten bundled fixtures is gap-dominated, so no hash could have moved whatever the change did.

I have made the corrected test_interior_holes_match_the_covered_byte_walk docstring say why it populates both sources, per your note.

Gates

Full suite on the rebased branch: 2092 passed, 2 skipped, 2593 subtests. ruff check and ruff format --check clean, make typecheck exit 0 with no error-level diagnostics. (#300's own tree, underneath this one, is 2059 passed, 2 skipped, 2593 subtests.)

[danielplohmann]

Reviewed. #300 is in as 50d3289, so I have rebased this onto current master and pushed it, along with one fix — details below, and the pre-push head is recorded so nothing is lost.

Pre-push head 6cae1c5aa2a9f6c3b1e6a73fea8a07e9d959038d, new head b833695e51fe3ad59c0ae933b208a69f2d127a4d.

The rebase itself was mechanical: --onto master 68b2626, all 17 commits applied clean, no conflict. A test merge did conflict on one line — self._code_area_index = None in the init() reset block, which git could not place because the squash reordered its neighbours — but a rebase applies each commit three-way and resolved it without asking. Verified content-neutral two ways rather than assumed:

• diff(old branch → rebased) and diff(old base → master) are the same 356 lines, and the only files that move are chore: cut v4.5.1 #319's and chore: correct the figures and the directory lookup #300 shipped #325's.
• diff(old base → old branch) and diff(master → rebased) are both 2,135 lines and identical but for one context line, inside a hunk whose neighbouring function chore: correct the figures and the directory lookup #300 shipped #325 rewrote. Your 17 commits survived byte for byte.

One bookkeeping note before anything else: your ten report hashes all change on this rebase, because master carries v4.5.1's version bump and your old base did not. smda_version is inside toDict(). Excluding it, I re-ran the comparison and it still holds — see below. Nothing is wrong when you see that table move.

---

The one thing I had to fix: _NOP_START_BYTES omits the REX prefixes

perf(intel): match any-byte regexes without DOTALL and skip gap disasm gates the 15-byte disasm_lite probe on a first-byte set, with the comment "anything else cannot be a nop". In 64-bit that is not true of 0x40–0x4F. Every REX prefix can open an instruction capstone spells nop:

40 90        -> nop
48 0f 1f 00  -> nop
41 0f 1f 00  -> nop dword ptr [r8]

Swept against capstone over all 256 first bytes in both modes: 32-bit needs nothing beyond the set you had, 64-bit needs exactly the REX range on top of it.

The effect, driving nextGapCandidate() over a gap that opens with each form — the first address the scan offers:

gap opens with	master	this branch as pushed
0f 1f 00 (plain multi-byte nop)	0x4	0x4
48 0f 1f 00 (REX.W)	0x5	0x1
41 0f 1f 00 (REX.B)	0x5	0x1
40 90 (REX)	0x3	0x1

0x1 is the nop's own address: the scan stops recognising REX-padded alignment filler and books a candidate on the padding instead of stepping over it. The plain-nop row is the control.

Fixed in b833695 as a separate 64-bit set rather than by widening the shared one, because at 32 bits 0x40–0x4F are inc/dec and never a nop — admitting them unconditionally would spend a 15-byte disassembly on every inc or dec that opens a gap, which in a perf change is the wrong direction. Selected once per nextGapCandidate() call by bitness.

Two tests, both directions: the three encodings fail on the pre-fix source (4096 != 4100, 4096 != 4100, 4096 != 4098) and pass after, and a 32-bit test asserts disasm_lite is never reached for a REX byte, so the mode split cannot quietly collapse later.

No bundled fixture is REX-padded in a gap, which is exactly why the ten report hashes could not see it. That is your own third-defect note arriving a second time, from a different direction, and it is the reason I went looking at the byte level rather than trusting the hashes — so the generalisation earned its keep within one review of being written down.

What I checked and what held

• PriorityQueue pop order is preserved exactly. This was the one I most expected to find something in: the rewrite swaps other.element < self.element for a (neg_score, addr) min-heap, and FunctionCandidate.__lt__ reverses on address when scores tie, so it looks like the tie-break flips. It does not — the two reversals cancel. Property-tested against master's _MaxHeapItem over 2,000 random heaps: 0 mismatches.
• Report identity: 13 of 13 fixtures identical, under both candidate queues. BracketQueue is not the default and is not in your ten, and it is the queue whose update() call site the branch changes, so it is worth having on the record. (smda_version excluded, per the note above.)
• The escape cache does not leak across reports. The key holds the escaper class, bytes, mnemonic, operands and the bounds, but escapeBinary also reaches ins.getDetailed(), which decodes under the report's capstone engine — a mode that is not in the key. I could not construct a collision, and 3,988 functions across 12 fixtures hash identically whether analysed in one shared process or in fresh ones. Recording it because only lower_addr/upper_addr keep a 32-bit and a 64-bit image apart today, and that is accidental rather than designed; architecture and bitness in the key would make it deliberate.
• The AArch64 top-byte filter tables are exactly the achievable sets — not supersets. Derived from each pattern's mask (BL's 0xFC top mask gives exactly 0x94–0x97; all three prologue masks pin bits 31–24 outright, giving {0xA9, 0xD5, 0xF8}), then cross-checked by sampling ~2M words with rejected top bytes for zero misses. _wordsView indexing lines up with binary[4i+3] on both host byte orders, including the big-endian materialised path.
• getNormalizedBlockRefs' fast path preserves key order. I built a function whose self.blocks is deliberately out of ascending order to check — the slow path sorts at the end too, so sorted(self.blocks) matches by construction.
• Dropping fix_graph from get_nesting_depth is sound: it only adds empty successor lists, which cannot reach len(v) > 1. The re.DOTALL → [\x00-\xff] rewrites are set-equivalent with no stray . left behind.

Two notes, neither blocking, both ours

• finalizeAnalysis now creates empty successor entries. Iterating code_refs_from.items() rather than pairs means an addr_from whose destinations were all removed writes disassembly.code_refs_from[addr] = set(), where the old pair loop wrote nothing. Reachable — 30 occurrences over 2,839 calls on five fixtures — and two membership tests in DisassemblyResult (lines 131 and 280) can see it, though no bundled fixture's report changes. An if dests: guard makes it exact.
• Two getattr(self, "_code_area_index", None) reads where __init__ could define the attribute, which is the pattern refactor(common): type the attributes the dropped annotations rest on #320 removed elsewhere. The index is keyed on list identity, so an in-place mutation of code_areas would go unnoticed; nothing mutates it today. Related: the raw_binary hoist in analyzeFunction is safe only because the one in-analysis rebinder of binary_info.binary — the Delphi relocation pass — runs in the candidate phase. Your comment covers the dicts and sets; that one is worth naming beside them.

Gates on the pushed head

• python -m pytest tests/: 2094 passed, 2 skipped, 2596 subtests
• ruff check . and ruff format --check .: clean
• make typecheck: exit 0, 0 error-level diagnostics

Merging once CI is green. Thanks for the third-defect writeup in particular — it is the reason this review looked where it did.