chore: review follow-ups from the open-PR triage pass

[danielplohmann]

Closes the actionable half of #317 — five small corrections found while reviewing #302 through #311, none of which was worth blocking its PR on or opening a PR for on its own.

No behaviour change: the only src/smda/** edits are one bool() wrapper whose result is identical, and two comments.

What changed

README — the address-space section contradicted itself

It told a consumer the backend is named "in two places, report.architecture and metadata.language in toDict()". The second is wrong in exactly the direction that section exists to prevent:

cil      -> {'.net': 1.0}
dalvik   -> {'dalvik': 1.0}
intel    -> {'c/asm': 0.1, 'delphi': 0.0, '.net': 0.0, 'visualbasic': 0.0, 'go': 0.0, ...}
aarch64  -> {'c/asm': 0.1, 'delphi': 0.0, '.net': 0.0, ...}

metadata.language is a source-language score map. It carries a single decisive entry on the two managed backends and a distribution on the native ones — including a .net score. A consumer following that advice and branching on .net appearing in it can read a native report as managed, and then treat virtual addresses as file offsets, which is the precise mistake the section was added to stop.

The README already stated the score-map contract 130 lines further down ("SmdaReport.metadata.language is always a score map"), so the two halves disagreed. report.architecture is authoritative on all four backends and is now named as the field to branch on. The CilDisassembler docstring added by #308 was already careful here — it says "the language score map" — so only the consumer-facing half needed the correction.

smda_instruction_matches_capstone gets its -> bool back

#302 removed the annotation to satisfy ty 0.0.74's unsound-return-statement. The cause is upstream of the annotation: capstone_instruction is untyped, so .size is Unknown and Unknown * 2 == len(...) infers Unknown. bool() around the return makes the declared type true rather than deleting the declaration.

id: ruff becomes id: ruff-check

At ruff-pre-commit v0.16.x the hook reports itself as ruff (legacy alias). astral renamed it; the alias still resolves and will presumably be dropped in a future major. Verified both hooks run under the new id, and that ruff no longer resolves (No hook with id 'ruff' in stage 'pre-commit'), which is the intended state.

GAP_SEQUENCES gains a note about its reach

#304 added two CS-prefixed GCC nops to it while being titled and measured as a change to the alignment cut. That table is read in seven places outside the cut — five in intel/FunctionCandidateManager (the exact-length and any-length filler tests, the candidate scan, and the gap-length walk) and two in X86Backend — so an encoding added there sharpens all padding-aware discovery. Worth a comment, because it is what makes a measurement over a change to this table hard to attribute to one caller.

One test says what it is for

test_late_tailcall_does_not_rebuild_queue was renamed by #307 from test_new_scored_candidate_does_not_rebuild_queue, and its update.assert_not_called() is now trivially true: the AArch64 addTailcallCandidate no longer records a call reference, so it has no score to change and cannot reach candidate_queue.update. Kept rather than deleted — it is a reasonable guard against reintroducing scoring there — with a docstring saying so, so the next reader does not have to work out whether it is load-bearing.

Two items from #317 deliberately left out

Both turned out to need work upstream of the annotation rather than the annotation itself, which is worth recording as the reason #302 took the shortcut it did. I have added the detail to #317.

Typing SmdaFunction.blocks. Dict[int, List[SmdaInstruction]] is accurate — both population sites build SmdaInstruction objects — and it does restore getInstructionsForBlock's return type. But it surfaces two no-matching-overload errors at SmdaFunction.py:463 and :479, where getPicHashSequence and getOpcHashSequence do "".join(escaped_binary_seqs) over a list built from instruction.bytes, which #302 annotated Optional[str]. A block instruction always carries bytes in practice, so this is latent rather than live — but joining a possibly-None sequence is a real soundness gap and deserves its own change rather than a suppression here.

Narrowing extract_strings. Tuple[str, Any, Any, str] cannot be tightened while read_string, read_go_string and derefs are untyped: all three yield sites then infer tuple[Unknown, Unknown, Unknown, Unknown], so even str in the first position is unprovable and the annotation produces three unsound-yield errors. Typing those three helpers comes first.

Validation

Gate	Result
ty check src/smda/ fuzzing/ profiling/ .github/workflows/scripts/	exit 0, zero errors, warning count unchanged
ruff check .	All checks passed
ruff format --check .	260 files already formatted
pre-commit run ruff-check --all-files	Passed
pre-commit run ruff-format --all-files	Passed
full suite	1882 passed, 2 skipped, 2591 subtests

[github-actions]

📊 SMDA Performance Evaluation Benchmark Results

Generated on: 2026-09-07 15:02:43

Summary

Metric	Result
Correctness	✅ PASS — 0 / 155 common file(s) differ
Determinism	✅ PASS — base 3 run(s), PR 3 run(s)
Verdict	PR is faster
Median paired speedup	+16.68% (95% CI [+15.49%, +18.28%])
Timing noise band	±4.3%

Per-side Timing Context (best of 3/3 runs per file)

Side	Files	Functions	Median best time/file (s)	Sum of best times (s)	Throughput estimate (func/s)
base	155	175976	0.7905	305.44	~576
pr	155	175976	0.6155	257.20	~684

These context rows sum each file's best observed time across repeated runs; they are normalized comparison estimates, not single-run CI wall-clock times.

Paired per-file timing (positive speedup = PR faster):

Statistic	Value
Files compared	155
Median paired speedup	+16.68% (95% CI [+15.49%, +18.28%])
Mean speedup	+18.21% (95% CI [+16.65%, +19.79%])
Std dev / IQR	9.88% / 9.41%
Wilcoxon signed-rank p	0.0000 (n=155)

ℹ️ base and PR are timed on separate CI runners, so a small median difference can reflect per-runner hardware variance rather than code. Differences within the timing noise band above are reported as inconclusive; correctness and determinism are unaffected (they are not timing-based).

Determinism (self-check across repeated runs)

Side	Runs	Files	Deterministic	Median timing CV
base	3	155	✅	3.7%
pr	3	155	✅	4.3%

Pairwise run matrix (individual run medians, diagnostic)

Diagnostic only: each row compares one raw PR run against one raw base run. The headline verdict above uses paired per-file best-of-runs timings.

Comparison Run	PR Files	Base Files	Common	Function Set Matches	Med PR (s)	Med Base (s)	Med Diff (s)	Speedup %
pr_0 vs base_0	155	155	155	155/155	0.7980s	0.8477s	-0.0498s	+5.87%
pr_0 vs base_1	155	155	155	155/155	0.7980s	0.9605s	-0.1626s	+16.92%
pr_0 vs base_2	155	155	155	155/155	0.7980s	0.8918s	-0.0938s	+10.52%
pr_1 vs base_0	155	155	155	155/155	0.7811s	0.8477s	-0.0666s	+7.85%
pr_1 vs base_1	155	155	155	155/155	0.7811s	0.9605s	-0.1794s	+18.67%
pr_1 vs base_2	155	155	155	155/155	0.7811s	0.8918s	-0.1106s	+12.40%
pr_2 vs base_0	155	155	155	155/155	0.8027s	0.8477s	-0.0450s	+5.31%
pr_2 vs base_1	155	155	155	155/155	0.8027s	0.9605s	-0.1578s	+16.43%
pr_2 vs base_2	155	155	155	155/155	0.8027s	0.8918s	-0.0890s	+9.98%