docs(native): distinguish analysis memory from source bytes

Document initialized Ghidra analysis-memory bytes, source mappings and incomplete coverage. Retain the portable test-owned alternate ELF for liveness cancellation.

Validation: fresh docs:check and complete exact-head CI passed. Historical real Ghidra checks remain explicitly attributed to their recorded revision/platform in the PR.

Refs #3075.

.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -124,6 +124,26 @@ operation's full ordered list. Candidate capabilities describe possible
 providers. Top-level session capabilities describe the current route, and
 `analysis_provider_binding` identifies the selected provider.
 
+## Static memory and original file bytes
+
+For Ghidra, `read_bytes` reads initialized analysis memory, including loader
+fixups; it does not read a running process. Check `returned_bytes` and `complete`
+before decoding a table. An incomplete read is missing coverage, not a zero-filled
+tail. Use `list_segments` to inspect the selected block's initialization and address-space
+facts, and retain unavailable facts as unknown.
+
+Use `address_to_file_offset` to anchor one observed address to original file
+bytes. A mapping for the first address does not establish a contiguous mapping
+for an entire table, and loader fixups can make analysis bytes differ from source
+bytes. Keep source ranges and analysis-memory observations separate.
+
+A pointer table can refer to writable slots populated by a constructor rather
+than directly to immutable resources. An uninitialized block or an observed zero
+does not establish the slot's later runtime value. Follow `xrefs` and the relevant
+writer's assembly or pseudocode; distinguish recorded assignments from inferred
+execution order. Do not replace unreadable bytes with zeros or conclude that a
+resource is absent without the necessary initialization evidence.
+
 ## DOS MZ with Ghidra
 
 For an admitted DOS MZ target, use `inspect_native_load_image` to check measured
@@ -133,10 +153,8 @@ reported static image, not runtime DOS or PC-98 hardware behavior.
 
 For Ghidra decompilation, `procedure_pseudo_code` also accepts `procedure: "file-offset:0x..."`; CLI `rea decompile <path> --file-offset=0x... --provider ghidra` resolves the source byte offset internally. An unresolved 0x-prefixed numeric procedure selector also falls back to a unique file mapping. Existing symbols and analysis addresses win; multiple mappings fail as ambiguous. Preserve the returned file-offset and address locations and raw selection observations. ELF virtual addresses are distinct from file offsets; never assume an arbitrary offset plus image base is an analysis address.
 
-Use `read_bytes` for initialized analysis memory and `address_to_file_offset` to
-anchor one observed address to original file bytes. Loader fixups can change a
-word; a source offset does not imply byte equality. Complete function body ranges
-use inclusive ends and can contain gaps. Do not treat the enclosing span as code.
+Complete function body ranges use inclusive ends and can contain gaps. Do not
+treat the enclosing span as code.
 For packed targets, retain the original and separately derived artifact identities;
 decompiling an unpacking stub does not recover the unpacked program.
 

docs/mcp-contracts.md

@@ -540,6 +540,25 @@ temporary source files are declared as `launchesProcess` and `writesFilesystem`,
 including for a single JavaScript source. This internal analysis does not execute
 the supplied application code.
 
+## Static Ghidra bytes and source mappings
+
+`read_bytes` returns initialized analysis memory, including loader fixups, rather
+than live process memory. Check `returned_bytes` and `complete` before decoding:
+reads stop at unmapped or uninitialized bytes. Missing bytes are unknown; do not
+pad an incomplete read with zeros and treat the result as an observation.
+
+`list_segments` reports memory-block initialization and address-space facts.
+`address_to_file_offset` maps one address through the provider's source-byte
+mapping. A successful start-address mapping does not establish that an entire
+range is contiguous in the original file, or that its bytes equal analysis
+memory after loader fixups. Uninitialized, missing, and ambiguous mappings fail
+explicitly; preserve the reported failure rather than guessing an offset.
+
+For constructor-populated pointer or resource slots, a static zero is not proof
+of a later null value. Inspect the slot's `xrefs` and the writer's assembly or
+pseudocode, retaining uncertainty about execution order and runtime values.
+These operations inspect static evidence and do not execute the target.
+
 ## Ghidra first-query deadlines and recovery
 
 A successful MCP initialize handshake establishes the REA connection.

src/application/binary/BinarySessionLiveness.test.ts

@@ -1,3 +1,7 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";
+import { elf } from "../../domain/binaryTarget.fixture.js";
 import { describe, expect, it } from "vitest";
 
 import {
@@ -235,7 +239,12 @@ it("clears retired runtime availability after cancelled-switch restoration", asy
   const initialRunId = sessionRunId(await session.status());
 
   const controller = new AbortController();
-  const switching = session.open("/bin/ls", { signal: controller.signal });
+  const alternate = join(
+    await createTestTempDirectory("rea-liveness-switch-"),
+    "alternate.elf",
+  );
+  await writeFile(alternate, elf(2, 1, 62));
+  const switching = session.open(alternate, { signal: controller.signal });
   await closing;
   controller.abort();
   releaseClose();