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

ADDED Requirements

Requirement: Query the region containing an address

WhiteMagic SHALL return the mapped memory region that contains a given address, including its base, size, protection, state, and type.

Scenario: query a committed address

• WHEN the region containing a known committed address is queried
• THEN it MUST return a region whose base and size bracket that address and whose protection reflects the page's actual protection

Scenario: region membership test

• WHEN a region is asked whether it contains an address
• THEN it MUST return true only for addresses within [base, base + size)

Requirement: Enumerate mapped regions

WhiteMagic SHALL enumerate the mapped memory regions of the target from the lowest address upward, lazily.

Scenario: enumeration walks the address space

• WHEN the target's regions are enumerated
• THEN the sequence MUST yield contiguous, non-overlapping regions ascending by base address until the end of the queryable address space

Scenario: early stop

• WHEN a caller stops consuming the enumeration after the first match
• THEN enumeration MUST NOT query the entire address space

Requirement: Scoped protection change

WhiteMagic SHALL change the protection of a region and restore the original protection when the returned scope is disposed.

Scenario: protection is applied within the scope

• WHEN a protection-change scope is created for a region with a new protection
• THEN the region's protection MUST be the requested value for the duration of the scope

Scenario: protection is restored on dispose

• WHEN the protection-change scope is disposed
• THEN the region's protection MUST be restored to the value it had before the scope was created

Scenario: restore on exception

• WHEN the guarded body throws before the scope is disposed
• THEN the original protection MUST still be restored as the scope unwinds