Document that memory/allocations persist across runs (multi-export is one accreting process)

[williballenthin]

Summary

Heap/VirtualAlloc allocations, dropped-file handles, and other process state persist across runs within a single emulation. This is defensible as same-process modeling, but it means "invoke every export" (all_entrypoints=True) is not a clean per-export probe — it is a single, accreting process, and later exports observe earlier exports' allocations and globals.

Impact

Analysts and library users can misread multi-export reports as independent per-export results. Combined with the CPU-register and stack bleed issues, the cross-run coupling is stronger than expected.

Proposed resolution (obvious — primarily documentation)

Document the semantics explicitly in doc/reporting.md and doc/library.md: runs share process-global memory by design, and (after the register/stack-reset fixes) CPU/thread context is reset per run while process memory is not. If a clean per-export probe is desired, that would be a separate opt-in feature (fresh process state per run).

Testing / validation

N/A for the documentation change. If an opt-in "isolate runs" mode is later added: allocate in run 1, assert the allocation is absent at the start of run 2 under the isolation flag.

Found during the architecture review on branch claude/windows-emulator-architecture-qvaabb.

[williballenthin]

alternatively, could we reset memory allocations across runs? what would be the impact there? right now, i think the ordering of the runs is somewhat unspecified, so i don't think we should rely on the memory allocations across these runs.

[williballenthin]

PR created: #315

Now for the #307 research. The research agent completed with thorough findings. Here's the summary:

---

Issue #307: Resetting memory allocations between runs

What accumulates across runs

When running with all_entrypoints=True, everything except the stack pointer and SEH tracker persists between runs:

• Memory: VirtualAlloc, HeapAlloc, GlobalAlloc, MapViewOfFile regions — all tracked in memmgr.py:self.maps with api.* tags
• OS managers (all instance-level, never reset): FileManager (file/pipe handles, dropped files), NetworkManager (sockets), RegistryManager (keys), CryptoManager
• Object manager (self.om): all kernel objects (Events, Mutants, Threads, file objects) and their handles accumulate
• Module globals: writable .data/.bss sections retain mutations from earlier runs
• Other: self.ansi_strings, self.unicode_strings, self.global_data, self.callbacks, self.veh_handlers, self.child_processes

What "clear memory allocations" would take

Option A — Unmap dynamic allocations only (~50-80 lines): After each run, mem_free every MemMap with an api.* tag, clear heap_allocs, close file/net handles. Problem: breaks exports that reference DllMain-allocated memory (very common pattern — DllMain does HeapAlloc for globals, exports use them).

Option B — Snapshot/restore after DllMain (~150-200 lines, recommended): After DllMain completes, snapshot all self.maps, the contents of every writable module section, and manager state dicts. Before each export run, restore from that snapshot. This preserves DllMain's initialization while isolating exports from each other.

The key enabler: original section data is already retained in RuntimeModule._image.regions[].data, so .data section restoration is feasible without re-parsing the PE.

Risks

1. DllMain dependency (the big one): DllMain commonly allocates heaps, initializes global pointers, creates sync objects, and sets up TLS. Option A would break this pattern. Option B handles it correctly.

2. Intentional cross-export state: Some DLLs follow Init/DoWork/Cleanup where exports are called in sequence and share state. This argues strongly for making reset opt-in (e.g., isolate_runs=True).

3. PEB/process heap: The process heap (emu.process_heap) is created during setup and referenced via PEB. If we free heap allocations that include it, the PEB pointer becomes dangling. Must exclude emu.*-tagged regions.

4. Handle value collisions: HandleAllocator is monotonic. If left alone, no collision risk. If reset, old leftover references could collide.

5. Dropped file attribution: The profiler already captures dropped files per-run in on_run_complete, so resetting the file manager doesn't lose attribution — it's already recorded.

Recommended approach

An opt-in isolate_runs=True flag on run_module that triggers snapshot/restore. Implementation:

1. After the DllMain run (run.type == "dll_entry.DLL_PROCESS_ATTACH"), snapshot maps, writable section contents, and manager state
2. Before each export run, restore the snapshot — unmap maps not in the snapshot, restore .data section bytes, reset manager dicts
3. Leave HandleAllocator counters alone (monotonic, no collision)
4. Key files: speakeasy/windows/win32.py (on_run_complete / _exec_next_run), speakeasy/memmgr.py

This is a non-trivial feature (~150-200 lines) but tractable, and the infrastructure (retained section data, tagged memory maps) is already in place.

---

No deviations from plan. No surprises — the codebase already has the hooks needed for snapshot/restore.