docs(docs): say which address space a report's offsets are in

[r0ny123]

A managed report's function and instruction offsets are file offsets. The native backends report virtual addresses. Nothing in the repository said so, so a consumer correlating a managed report with a native one — or with base_addr plus an RVA, or with any other tool's output — was silently comparing two different address spaces.

Two backends are affected, not one:

report.architecture	what an offset is
intel, aarch64	a virtual address — base_addr plus an RVA
cil	the offset of the method body in the assembly file
dalvik	the offset of the code item in the DEX file

The two managed cases differ in why, which is worth recording. A CIL method has an RVA and CilDisassembler reports the file offset instead — that is a choice. A DEX carries no load address at all, so for Dalvik the file offset is the only address there is. The consequence for a consumer is identical either way: adding base_addr to one of them produces a number that means nothing.

The decision: document it, do not move it

The offsets are a public compatibility surface that downstream consumers index on. Converting them would change every stored managed report's addresses; carrying both would change the report schema. Either is a deliberate decision about the format rather than a bug fix, and neither belongs in a change that can be made without the people who consume it. What was actually missing is the statement.

The second half of the statement matters as much as the first: a report already names the backend that produced it, twice — report.architecture, and metadata.language in toDict(). So a consumer has what it needs to apply the right rule, once it knows there are two.

What changed

• A README subsection under Usage, beside the raw-buffer section that covers the other thing about a report you cannot infer from it.
• Class docstrings on CilDisassembler and DalvikDisassembler, at the places the conversion is actually made.
• tests/testCilAddressSpace.py.

No behaviour change. The only edits under src/smda/** are docstrings.

The tests

Both halves pin the contract against a second parser, not against the file's length — with base_addr at 0 an address inside the image proves nothing about which space it is in, and that weaker assertion would pass on a report that had been converted to virtual addresses.

• CIL, via dnfile: every recovered method sits at its body's file offset (MethodDef.Rva through get_offset_from_rva), and none sits at the virtual address of the same method (ImageBase + Rva). The second is the control that makes the first mean something.
• Dalvik, via LIEF: all 2,219 recovered offsets on the bundled DEX fixture are code_offset values LIEF independently reports for the same file.
• A third asserts the fields a consumer would branch on are actually populated, since the README now tells people to read them.

The Dalvik half is a correction to the first draft of this, which said offsets are virtual addresses on "every backend but one". That was wrong in the direction that matters: documenting only CIL would have told a consumer to read Dalvik offsets as addresses, the exact error the section exists to prevent.

Validation

ruff check / ruff format --check pass, full suite green on this branch rebased onto current master (1820 passed, 1 skipped, 2584 subtests). Diff coverage reports no measurable lines, because the only src/smda/** lines are docstrings.

Relationship to #299 and #300

This change is also sitting inside #299 and #300. Both of those were opened from branches that had my fork's master merged into them repeatedly, so their diffs are much wider than their titles suggest and they overlap each other as well.

This PR is the same change on its own, rebased onto current master, so it can be reviewed and measured for what it actually is. If you would rather take it through one of those, close this one; if you take this one, the matching hunks fall out of theirs on rebase.

The ty commit at the tip

The last commit on this branch is #302's fix, cherry-picked unchanged.

Master fails Code Quality on its own right now: 572acd7 bumped ty to 0.0.74, and its new unsound-return-statement / unsound-assignment rules become errors under [tool.ty.rules] all = "error". That is 41 errors across 15 files, none of which this PR touches — so every PR opened against master inherits a red check that says nothing about its own diff.

Carrying #302's commit here means this PR's CI reflects only this PR's work. It is the same commit, unmodified, so the moment #302 lands this one is empty and falls out on rebase — there is nothing to untangle later. If you would rather look at this branch without it, merge #302 first and I will drop it.

Checked against ty 0.0.74 itself rather than whatever an older local pin resolves to: on master it exits 1 with 41 errors, on this branch it exits 0 with none.