whitemagic/openspec/changes/add-thread-region-finder/specs/thread-control/spec.md

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