Add process discovery helpers and Magic facade accessors

Introduces ApplicationFinder (by name/title/handle), Magic.Open overloads, and Magic.Threads/Regions/QueryRegion accessors. Closes section 3 of add-thread-region-finder and updates tasks/comparison doc.
2026-07-22 16:04:53 +02:00
parent 8f988768fe
commit 3e294dc846
12 changed files with 624 additions and 2 deletions
@@ -0,0 +1,57 @@
+## ADDED Requirements
+
+### Requirement: Enumerate target threads
+
+WhiteMagic SHALL enumerate the threads belonging to the target process and expose each as a controllable thread handle.
+
+#### Scenario: enumerate returns the target's threads
+- **WHEN** the threads of an open target are enumerated
+- **THEN** the result MUST contain a handle for each thread owned by the target process and none owned by other processes
+
+#### Scenario: resolve the main thread
+- **WHEN** the main thread is requested
+- **THEN** it MUST return the earliest-created thread of the target process
+
+#### Scenario: get a thread by id
+- **WHEN** a thread is requested by its thread id
+- **THEN** it MUST return a handle bound to that thread, or fail deterministically if the id is not a thread of the target
+
+### Requirement: Suspend and resume a thread
+
+WhiteMagic SHALL suspend and resume an individual target thread and report the prior suspend count.
+
+#### Scenario: suspend increments the suspend count
+- **WHEN** a running thread is suspended
+- **THEN** the thread MUST stop executing and the returned prior suspend count MUST reflect its state before the call
+
+#### Scenario: resume restores execution
+- **WHEN** a previously suspended thread is resumed to a zero suspend count
+- **THEN** the thread MUST resume executing
+
+### Requirement: Read and write thread context
+
+WhiteMagic SHALL read and write a target thread's register context, selecting the context layout that matches the target's bitness.
+
+#### Scenario: round-trip a register value
+- **WHEN** a thread's context is read, a register is modified, and the context is written back
+- **THEN** a subsequent read MUST reflect the modified register value
+
+#### Scenario: bitness-correct context
+- **WHEN** the target is a 32-bit (WOW64) process
+- **THEN** the WOW64 context layout MUST be used, and for a 64-bit target the native layout MUST be used
+
+### Requirement: Scoped thread freeze
+
+WhiteMagic SHALL provide a scoped freeze that suspends a selected set of target threads and resumes exactly those threads when the scope is disposed, including when the guarded body throws.
+
+#### Scenario: freeze suspends selected threads
+- **WHEN** a freeze scope is created over a set of threads
+- **THEN** each of those threads MUST be suspended for the duration of the scope
+
+#### Scenario: dispose resumes only the frozen threads
+- **WHEN** the freeze scope is disposed
+- **THEN** exactly the threads it suspended MUST be resumed, and threads suspended by other callers MUST be left unchanged
+
+#### Scenario: exception in the body still resumes
+- **WHEN** the guarded body throws before the scope is disposed
+- **THEN** the frozen threads MUST still be resumed as the scope unwinds