Add whitemagic-foundation OpenSpec design; isolate reference libs

Design-only foundation for WhiteMagic, a .NET 8 x64 library unifying the four studied process-manipulation libs. Adds proposal, design (7 decisions), 7 capability specs, and TDD task breakdown; all validate strict. Move Blackmagic, Blackmagic-old, GreyMagic, MemorySharp, fasm into reference/ (gitignored) — studied, not built here; each has its own upstream repo and nested .git. Rewrite plan doc paths to reference/. Corrects two factual defects found in review: - current BlackMagic has no D3D EndScene hook; MainThreadPump is net-new built on DetourManager, not a port - no BlackMagic.slnx exists; task 1.3 creates a fresh solution Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-21 16:50:03 +02:00
commit 4405af15fd
44 changed files with 4495 additions and 0 deletions
@@ -0,0 +1,57 @@
+## ADDED Requirements
+
+### Requirement: Pattern scanning with mask
+
+WhiteMagic SHALL scan process memory for a byte signature with a wildcard mask, returning the address of the first match or `IntPtr.Zero` when no match is found. Scans SHALL be available over an explicit range, a single module, and all modules.
+
+#### Scenario: pattern found
+- **WHEN** a known byte sequence is scanned for with a matching mask over a range containing it
+- **THEN** the returned address MUST point at the first occurrence
+
+#### Scenario: wildcard mask
+- **WHEN** the mask marks positions as wildcards (e.g. `"xx?x"`)
+- **THEN** those byte positions MUST be ignored during matching
+
+#### Scenario: pattern not found
+- **WHEN** a pattern absent from the range is scanned for
+- **THEN** the result MUST be `IntPtr.Zero`
+
+### Requirement: Pattern scan cache
+
+The scanner SHALL cache resolved pattern results keyed by pattern and mask, returning the cached address on repeat lookups, and SHALL expose an operation to clear the cache.
+
+#### Scenario: repeat lookup served from cache
+- **WHEN** the same pattern and mask are scanned twice without clearing the cache
+- **THEN** the second lookup MUST return the same address without rescanning memory
+
+#### Scenario: cache cleared
+- **WHEN** the cache is cleared
+- **THEN** the next lookup MUST rescan memory
+
+### Requirement: PE header parsing
+
+WhiteMagic SHALL parse the PE headers of a module to expose its sections and entry point without executing the module.
+
+#### Scenario: sections enumerated
+- **WHEN** a valid PE module is parsed
+- **THEN** its section names, virtual addresses, and sizes MUST be enumerable
+
+#### Scenario: entry point located
+- **WHEN** a valid PE module is parsed
+- **THEN** the parsed entry-point RVA MUST match the module's header
+
+### Requirement: Named remote allocation
+
+WhiteMagic SHALL allocate a chunk of remote memory subdivided into named regions, allowing typed read/write and address lookup by name, and freeing the whole chunk on dispose.
+
+#### Scenario: write and read by name
+- **WHEN** a named region is allocated and `Write<int>("count", 5)` then `Read<int>("count")` is called
+- **THEN** the result MUST equal `5`
+
+#### Scenario: address by name
+- **WHEN** a region named `"buffer"` is allocated
+- **THEN** requesting its address MUST return `chunkBase + regionOffset`
+
+#### Scenario: freed on dispose
+- **WHEN** the allocation is disposed
+- **THEN** the underlying remote memory MUST be released