whitemagic/openspec/changes/add-thread-region-finder/proposal.md

Why

The whitemagic-foundation review found WhiteMagic is a superset of GreyMagic and current BlackMagic, but not yet of MemorySharp. Three genuinely useful capabilities MemorySharp (and, for threads, current BlackMagic's SThread) shipped are missing from WhiteMagic:

1. Thread control — WhiteMagic calls SuspendThread/ResumeThread only internally inside DllInjector thread-hijack. There is no public surface to enumerate a target's threads, suspend/resume them, or freeze them for the duration of an edit. Freezing threads is table-stakes for memory editing/trainers (MemorySharp: ThreadFactory/RemoteThread/FrozenThread; BlackMagic: SThread).
2. Memory-region query — WhiteMagic changes page protection inline inside Detour but exposes no VirtualQueryEx region walk, no query-region-at-address, and no reusable scoped protection helper (MemorySharp: RemoteRegion/MemoryProtection). Callers cannot inspect what is mapped, its protection, or safely flip protection around a write.
3. Process discovery — no way to open a target by name/window/title; the caller must obtain a PID out of band (MemorySharp: ApplicationFinder).

These are all additive, low-risk surfaces that sit on the existing MemoryBase/SafeMemoryHandle and native P/Invoke layer. None requires the deferred managed-loader work.

What Changes

• Thread control (new capability thread-control): RemoteThread (open by id, suspend/resume, get/set context, get TEB, join), ThreadFactory (enumerate the target's threads, get main thread, get-by-id), and FrozenThread/Freeze() returning an IDisposable scope that suspends a set of threads and resumes them on dispose.
• Memory-region query (new capability memory-region): MemoryRegion (a queried VirtualQueryEx result — base, size, protection, state, type), region enumeration across the target's address space, query-region-containing-an-address, and a ChangeProtection(...) helper returning an IDisposable scope that restores the original protection on dispose.
• Process discovery (added to existing capability high-level-api): an ApplicationFinder/Magic.Open overloads to attach by process name, window title, or window handle, plus enumeration of candidate processes.

No behavior of existing WhiteMagic types changes; these are new types plus additive Magic facade members and new native imports.

Capabilities

New Capabilities

• thread-control: Enumerate, suspend/resume, freeze (scoped), and read/write the context of a target process's threads.
• memory-region: Query and enumerate mapped memory regions (VirtualQueryEx) and change page protection through a scoped, auto-restoring helper.

Modified Capabilities

• high-level-api: Adds process discovery — attach a target by name/window/handle and enumerate candidates.

Impact

• New code: WhiteMagic/Thread/RemoteThread.cs, ThreadFactory.cs, FrozenThread.cs; WhiteMagic/Memory/MemoryRegion.cs, MemoryRegionEnumerator (or methods on MemoryBase), ProtectionScope; WhiteMagic/Process/ApplicationFinder.cs; additive Magic facade members.
• New native imports: Thread32First/Thread32Next + CreateToolhelp32Snapshot (or NtQueryInformationProcess thread walk), VirtualQueryEx, MEMORY_BASIC_INFORMATION. OpenThread/Suspend/Resume/Get/SetThreadContext already exist in NativeMethods.
• No dependency change: pure P/Invoke over the existing core. No FASM, no Iced, no managed loader.
• No changes to BlackMagic/MemorySharp/GreyMagic or their tests.
• Platform: unchanged — bitness-agnostic (x86 + x64); thread context read honors the target's bitness like the existing hijack path.