Implement engine-bridge PoC v1 (#9)

- Add Recordingtest.EngineBridge library (IEngineSnapshot, HmEgSnapshot skeleton, MetadataLoader, CandidateFinder, CatalogWriter). - Add Recordingtest.EngineBridge.Probe console exe that dumps hmeg-types.json and hmeg-candidates.json to docs/engine-catalog. - Add Recordingtest.EngineBridge.Tests (xUnit, 6 tests). - Add probe design doc with plugin-masquerade recommendation. - Static analysis only; SUT is never executed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 15:48:58 +09:00
parent 13dc4109d8
commit 2a4f1d3fa4
16 changed files with 127677 additions and 0 deletions
--- a/docs/contracts/engine-bridge.md
+++ b/docs/contracts/engine-bridge.md
@@ -0,0 +1,77 @@
+# Sprint Contract — engine-bridge (PoC v1)
+
+**Owner:** Generator
+**Depends on:** sut-prober (assemblies.json), SUT PDB 동봉
+**Issue:** #9
+
+## Goal
+
+HmEG 3D 엔진 내부 상태(선택된 객체, 카메라, 씬 그래프)를 recordingtest에서 읽을 수 있는 경로를 확보한다. PoC v1은 **정적 탐색 + API 초안 + in-process probe 설계 문서**까지. 실제 SUT attach 및 런타임 검증은 v2로 연기(샌드박스 제약).
+
+## Definition of Done
+
+- [ ] `Recordingtest.EngineBridge` 라이브러리 + `Recordingtest.EngineBridge.Probe` 콘솔 exe
+- [ ] **정적 분석**: `System.Reflection.MetadataLoadContext`로 `EG-BIM Modeler/HmEG.dll`, `HmGeometry*.dll`, `Editor*.dll`을 로드해 public/internal 타입 열거 (SUT 실행 금지)
+- [ ] **후보 식별**: 다음 키워드를 포함하는 타입·프로퍼티·메서드를 카탈로그화:
+  - `Select` / `Selection` / `Picked`
+  - `Camera` / `View` / `Viewport` / `EyePoint`
+  - `Scene` / `Document` / `World` / `Root`
+  - `Render` / `Draw` / `Frame`
+- [ ] 출력: `docs/engine-catalog/hmeg-types.json`, `hmeg-candidates.json`
+  - `hmeg-types.json`: 어셈블리별 `{ assembly, typeName, isPublic, namespace }`
+  - `hmeg-candidates.json`: 후보별 `{ category, assembly, typeName, memberKind(Property|Method|Event), memberName, signature }`
+  - **결정성**: 정렬된 출력, 2회 실행 후 git diff 비어야 함
+- [ ] **API 초안**: `IEngineSnapshot` 인터페이스 + DTOs:
+  ```csharp
+  public interface IEngineSnapshot {
+      IReadOnlyList<string> SelectedObjectIds { get; }
+      CameraState Camera { get; }
+      SceneSummary Scene { get; }
+      bool IsRenderComplete { get; }
+  }
+  public sealed record CameraState(double[] EyePoint, double[] Target, double[] Up, double Fov);
+  public sealed record SceneSummary(int ObjectCount, string? DocumentPath);
+  ```
+  - 실제 구현체 `HmEgSnapshot`은 **skeleton**(throw NotImplementedException)으로 두되, 리플렉션 접근 지점(타입 이름)을 상수로 정의하고 정적 분석 카탈로그에서 실제 존재 확인
+- [ ] **Probe 설계 문서** `docs/engine-bridge-probe-design.md`:
+  - in-process injection 옵션 3가지 (AssemblyLoadContext attach vs. CLR profiler vs. inline MSIL patching) 장단점 + 권고
+  - 렌더 완료 신호 후보 (property polling vs. event subscription) + 예상 레이턴시
+  - AutomationPeer 대체 경로와의 비교
+- [ ] xUnit 테스트 ≥ 5:
+  - `MetadataLoader_LoadsHmegAssembly_WithoutExecution` — MetadataLoadContext 사용 확인
+  - `CandidateFinder_FindsSelectionRelatedTypes` — 실제 HmEG.dll 로드 후 `Selection` 키워드 포함 타입이 1개 이상
+  - `CatalogSerializer_OutputsSorted_Idempotent` — 2회 생성 시 byte-identical
+  - `IEngineSnapshot_DefaultInstance_ThrowsNotImplemented` — skeleton 확인
+  - `CandidateCategories_AllFourPresent` — Select/Camera/Scene/Render 4개 카테고리가 카탈로그에 존재
+- [ ] `dotnet build` green + `dotnet test` all pass
+- [ ] SUT 폴더 쓰기 접근 없음 (grep으로 확인)
+- [ ] 실행 경로: `dotnet run --project src/Recordingtest.EngineBridge.Probe -- --sut "EG-BIM Modeler" --out docs/engine-catalog`
+
+## Out of scope (v2 이후)
+
+- 실제 SUT 프로세스 attach / 리플렉션 호출 실행
+- 런타임 값 캡처
+- player 통합
+- AutomationPeer 자동 부착
+
+## Interfaces
+
+- **Inputs:** SUT 폴더 경로
+- **Outputs:** `docs/engine-catalog/*.json`, `docs/engine-bridge-probe-design.md`
+- **Side effects:** 없음 (MetadataLoadContext는 순수 메타데이터 로드)
+
+## Evaluation plan
+
+1. `dotnet build recordingtest.sln` green
+2. `dotnet test tests/Recordingtest.EngineBridge.Tests` — 5 pass
+3. `dotnet run --project src/Recordingtest.EngineBridge.Probe -- --sut "EG-BIM Modeler"` exit 0
+4. `hmeg-candidates.json` 카테고리 4개 전부 존재, 각 카테고리 엔트리 ≥ 1
+5. 2회 실행 후 git diff 비어있음
+6. `IEngineSnapshot` 인터페이스 + 상수가 존재하며, 상수 타입 이름이 실제 카탈로그에 포함됨을 확인하는 테스트 1개
+7. Probe 설계 문서가 3개 옵션 비교 + 권고를 포함
+
+## Risks
+
+- HmEG 내부는 obfuscation이 걸려있을 수 있음 → 발견된 타입 수가 적으면 휴리스틱 강화 필요
+- Selection 타입이 `internal`이면 PoC v1에서도 메타데이터로는 보임 (접근 가능). 런타임 접근은 v2.
+- MetadataLoadContext는 의존 어셈블리 resolver 필요 → `PathAssemblyResolver(new[] { sutRoot, dotnetRuntimeDir })` 세팅 필수.
--- a/docs/engine-bridge-probe-design.md
+++ b/docs/engine-bridge-probe-design.md
@@ -0,0 +1,97 @@
+# engine-bridge Probe Design (PoC v2 blueprint)
+
+Related: issue #9, contract `docs/contracts/engine-bridge.md`.
+
+## Goal
+
+Provide recordingtest with a reliable, low-latency read path into HmEG's live runtime state
+(selected object IDs, camera state, scene summary, render-complete flag) while the SUT
+(`EG-BIM Modeler`) is running, so golden-file scenarios can checkpoint internal state alongside
+saved `.hmeg` files.
+
+PoC v1 (this sprint) delivers static catalogs and a skeleton API. PoC v2 must actually get
+into the process. The rest of this document surveys the options and picks one.
+
+## Options
+
+### 1. `AssemblyLoadContext` side-load in the recordingtest process
+Load `HmEG.dll` into a secondary `AssemblyLoadContext` inside the recordingtest test runner.
+
+- Pros: no native code, single process, trivial lifetime.
+- Cons: **we would be reading our own copy of HmEG, not the SUT's**. No live camera, no live
+  selection. Any singleton the SUT maintains is unreachable.
+- Verdict: **not viable** for read-live-state; listed for completeness so reviewers don't
+  propose it. Static metadata scanning (what PoC v1 already does) is the legitimate use of
+  this family of APIs.
+
+### 2. CLR profiling API (ICorProfilerCallback)
+Ship a native profiler DLL registered via `CORECLR_PROFILER*` env vars. The profiler attaches
+at CLR startup, can `SetILFunctionBody` on HmEG methods, or hand managed code to a bootstrap
+assembly that installs hooks.
+
+- Pros: deepest reach, survives obfuscation, hooks JIT. Can intercept private methods.
+- Cons: native DLL (C/C++), must match CLR bitness and version, requires SUT restart with
+  env vars set, complex failure modes, AV-sensitive.
+- Verdict: **fallback** for a zero-cooperation scenario. Too heavy for first attempt.
+
+### 3. In-process managed injector (e.g. `Ezez.CLRInjection`, `SharpMonoInjector` style)
+`CreateRemoteThread` + `LoadLibrary` on a small native bootstrap that starts a CLR host and
+runs our managed bridge DLL inside the SUT's AppDomain. Bridge uses ordinary reflection to
+reach `HmEGAppManager` and exposes state via named pipe or loopback HTTP.
+
+- Pros: attach at runtime, no SUT restart if the SUT is already running. Pure managed once
+  bootstrapped. Symmetrical with how profilers like dotTrace attach on demand.
+- Cons: Windows-only, bitness must match (SUT is x64 WPF), AV alarms, fragile across .NET
+  runtime versions, process isolation privileges required. CoreCLR hosting from a foreign
+  thread is tricky compared to classic Framework.
+- Verdict: viable but operationally painful. Use only if option 4 is blocked.
+
+### 4. Plugin masquerade via SUT's existing MEF pipeline (RECOMMENDED)
+The SUT already loads plugins from `EG-BIM Modeler/Plugins/` using MEF (per `CLAUDE.md` §1
+and `docs/sut-catalog/plugins.md`). Drop `Recordingtest.EngineBridge.SutPlugin.dll` into that
+folder. It exports the plugin contract the SUT expects, grabs a reference to
+`HmEGAppManager` (or whatever the static catalog shows is the canonical accessor), and
+publishes `IEngineSnapshot` over a localhost endpoint (named pipe `recordingtest-bridge` or
+HTTP on 127.0.0.1).
+
+- Pros: legitimate extension point, no native code, no process injection, no AV noise, CI
+  friendly, single cooperating restart. Honors CLAUDE.md §5.7 ("SUT 침습 최소화 — 별도
+  어셈블리로 격리"). Integrates with dispatcher marshaling by design — the plugin runs on
+  the WPF UI thread when called back.
+- Cons: requires SUT restart once to load the plugin; depends on MEF contract remaining
+  stable; small IPC surface to keep deterministic.
+- Verdict: **chosen path for PoC v2**.
+
+### 5. AutomationPeer (comparison baseline)
+Add a custom `UIA` AutomationPeer on the 3D viewport that exposes selection via the standard
+`SelectionPattern` and camera via custom properties.
+
+- Pros: standard, debuggable with `inspect.exe`.
+- Cons: requires SUT source changes; cannot easily expose full scene graph or render-complete
+  without contortions; limited to what UIA patterns can model.
+- Verdict: parallel track for exposing UI-shaped state. Not a replacement for the bridge.
+
+## Render-complete signal
+
+| Approach | Latency (expected) | Notes |
+|---|---|---|
+| Poll `IsDirty`-like property at ~16 ms | ~1 frame | simple, robust; costs a reflection call per tick |
+| Subscribe to a `FrameRendered`/`Invalidated` event | event-driven, ~0 ms | best case; depends on such an event existing (the static catalog will tell us — look for `render` candidates with `MemberKind=Event`) |
+| WPF `CompositionTarget.Rendering` from inside the plugin | ~1 frame | works even if HmEG has no event; UI-thread bound |
+
+Recommendation: try event subscription first via the candidates catalog; fall back to
+`CompositionTarget.Rendering` inside the MEF plugin because the plugin already runs on the
+UI thread.
+
+## Recommendation
+
+PoC v2: **implement option 4 (plugin masquerade)** with a named-pipe JSON protocol that
+produces the `IEngineSnapshot` DTOs defined in this library. Option 2 (CLR profiler) is the
+documented fallback for a future "zero cooperation" scenario. Option 5 (AutomationPeer) is a
+parallel concern that belongs to `sut-prober` and `recorder`, not to engine-bridge.
+
+## Open questions (tracked, not blocking v1)
+
+- Exact MEF contract the SUT expects (see `docs/sut-catalog/plugins.md` — resolved before v2)
+- Whether HmEG exposes a `FrameRendered`-style event (answer will come from v1 catalog)
+- Selection identity: object GUID vs. transient index — needs a stable key for golden diffs
--- a/docs/engine-catalog/hmeg-candidates.json
+++ b/docs/engine-catalog/hmeg-candidates.json
--- a/docs/engine-catalog/hmeg-types.json
+++ b/docs/engine-catalog/hmeg-types.json
--- a/docs/history/2026-04-07_이슈9-engine-bridge-generator.md
+++ b/docs/history/2026-04-07_이슈9-engine-bridge-generator.md
@@ -0,0 +1,68 @@
+# 2026-04-07 이슈 #9 — engine-bridge PoC v1 (Generator)
+
+- **이슈**: kimminsung/recordingtest#9
+- **소요 시간**: ~25분
+- **Context 사용량**: ~55k tokens
+- **역할**: Generator (Sprint Contract `docs/contracts/engine-bridge.md` 기준 구현)
+
+## 범위
+
+Sprint Contract `engine-bridge` PoC v1의 DoD 항목만 구현. 스코프 이탈 없음.
+실제 런타임 attach / 값 캡처는 v2로 연기(계약 Out of scope).
+
+## 산출물
+
+### 라이브러리 `src/Recordingtest.EngineBridge/`
+- `IEngineSnapshot.cs` — `IEngineSnapshot` 인터페이스 + `CameraState`/`SceneSummary` 레코드
+- `HmEgSnapshot.cs` — skeleton (NotImplementedException), 리플렉션 앵커 상수
+  - `HmEgAssemblyHint="HmEG"`, `EditorManagerTypeHint="HmEGAppManager"`, etc.
+- `MetadataLoader.cs` — `MetadataLoadContext` + `PathAssemblyResolver` (SUT root + runtime dir)
+- `CandidateFinder.cs` — 4 카테고리 (select/camera/scene/render) 키워드 매칭
+- `CatalogWriter.cs` — 결정적 정렬된 JSON 출력 (WriteIndented + LF normalize + trailing newline)
+
+### Probe `src/Recordingtest.EngineBridge.Probe/`
+- `Program.cs` — `--sut`/`--out` 인자, 기본값 `EG-BIM Modeler` / `docs/engine-catalog`
+- SUT 폴더 없음 → exit 2
+- 카탈로그 2개 작성 + 요약 출력
+
+### 테스트 `tests/Recordingtest.EngineBridge.Tests/` (xUnit, 6개)
+1. `MetadataLoader_LoadsHmegAssembly_WithoutExecution`
+2. `CandidateFinder_FindsSelectionRelatedTypes`
+3. `CatalogSerializer_OutputsSorted_Idempotent`
+4. `HmEgSnapshot_DefaultInstance_ThrowsNotImplemented`
+5. `CandidateCategories_AllFourPresent`
+6. `HmEgSnapshot_Constants_MatchCatalog` (bonus)
+
+SUT 탐지는 `AppContext.BaseDirectory`에서 위로 걸어 `EG-BIM Modeler/HmEG.dll`을 찾는다.
+
+### 설계 문서 `docs/engine-bridge-probe-design.md`
+- 5가지 옵션 비교 (ALC side-load / CLR profiler / 관리 인젝터 / **MEF plugin masquerade** / AutomationPeer)
+- render-complete 신호 레이턴시 표
+- 권고: **plugin masquerade** (PoC v2), CLR profiler는 fallback
+
+### 카탈로그 `docs/engine-catalog/`
+- `hmeg-types.json`, `hmeg-candidates.json`
+
+### 솔루션
+- `recordingtest.sln`에 3개 프로젝트 추가 (`dotnet sln add`)
+
+## 실행 결과
+
+- `dotnet build recordingtest.sln` → 경고 0, 오류 0
+- 13 어셈블리 로드 (HmEG 2285 / EditorCore 416 / HmGeometry.V2 1669 / ...)
+- 후보: camera=4226, render=3602, scene=3081, select=726
+- 2회 실행 → `docs/engine-catalog` diff 없음 (결정성 확인)
+- `dotnet test tests/Recordingtest.EngineBridge.Tests` → 6/6 통과
+
+## 제약 준수
+
+- SUT 실행 없음 (MetadataLoadContext 전용, 메타데이터만)
+- `EG-BIM Modeler/`에 쓰기 없음
+- `PROGRESS.md`/`PLAN.md` 미수정 (Generator는 Evaluator pass 전까지 손대지 않음)
+- `TreatWarningsAsErrors` 유지, nullable 활성화
+- 추가 런타임 의존성: `System.Reflection.MetadataLoadContext` 8.0.0 + `System.Text.Json` 8.0.5 만
+
+## 남은 것 (Evaluator 몫)
+
+- `docs/contracts/engine-bridge.evaluation.md` 작성
+- pass 확정 후 `PROGRESS.md`/`PLAN.md` 갱신은 호출자가 수행
--- a/recordingtest.sln
+++ b/recordingtest.sln
@@ -27,6 +27,12 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Recordingtest.Runner", "src
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Recordingtest.Runner.Tests", "tests\Recordingtest.Runner.Tests\Recordingtest.Runner.Tests.csproj", "{6F9973EA-977A-4185-AF24-4E76D9D851C8}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Recordingtest.EngineBridge", "src\Recordingtest.EngineBridge\Recordingtest.EngineBridge.csproj", "{938D464B-B810-425F-83B6-52877B584DE2}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Recordingtest.EngineBridge.Probe", "src\Recordingtest.EngineBridge.Probe\Recordingtest.EngineBridge.Probe.csproj", "{B1EAD466-9C07-4C07-907C-3D5794F6689D}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Recordingtest.EngineBridge.Tests", "tests\Recordingtest.EngineBridge.Tests\Recordingtest.EngineBridge.Tests.csproj", "{0811AC32-E2A4-4BFD-A29A-6451F5756F10}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -181,6 +187,42 @@ Global
 		{6F9973EA-977A-4185-AF24-4E76D9D851C8}.Release|x64.Build.0 = Release|Any CPU
 		{6F9973EA-977A-4185-AF24-4E76D9D851C8}.Release|x86.ActiveCfg = Release|Any CPU
 		{6F9973EA-977A-4185-AF24-4E76D9D851C8}.Release|x86.Build.0 = Release|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Debug|x64.Build.0 = Debug|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Debug|x86.Build.0 = Debug|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Release|x64.ActiveCfg = Release|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Release|x64.Build.0 = Release|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Release|x86.ActiveCfg = Release|Any CPU
+		{938D464B-B810-425F-83B6-52877B584DE2}.Release|x86.Build.0 = Release|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Debug|x64.Build.0 = Debug|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Debug|x86.Build.0 = Debug|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Release|x64.ActiveCfg = Release|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Release|x64.Build.0 = Release|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Release|x86.ActiveCfg = Release|Any CPU
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D}.Release|x86.Build.0 = Release|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Debug|x64.Build.0 = Debug|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Debug|x86.Build.0 = Debug|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Release|x64.ActiveCfg = Release|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Release|x64.Build.0 = Release|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Release|x86.ActiveCfg = Release|Any CPU
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -197,5 +239,8 @@ Global
 		{7A5C0D53-BDFC-4AF6-8F4D-49E7EB8245F5} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{DADF0474-9EF3-4E8D-8139-93504E4F745D} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{6F9973EA-977A-4185-AF24-4E76D9D851C8} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{938D464B-B810-425F-83B6-52877B584DE2} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{B1EAD466-9C07-4C07-907C-3D5794F6689D} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{0811AC32-E2A4-4BFD-A29A-6451F5756F10} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 	EndGlobalSection
 EndGlobal
--- a/src/Recordingtest.EngineBridge.Probe/Program.cs
+++ b/src/Recordingtest.EngineBridge.Probe/Program.cs
@@ -0,0 +1,87 @@
+using System.Reflection;
+using Recordingtest.EngineBridge;
+
+namespace Recordingtest.EngineBridge.Probe;
+
+internal static class Program
+{
+    private static readonly string[] DefaultAssemblyPatterns =
+    {
+        "HmEG.dll",
+        "HmGeometry.dll",
+        "HmGeometry.V2.dll",
+        "HmTriangle.dll",
+        "EditorCore.dll",
+        "Editor*.dll",
+    };
+
+    internal static int Main(string[] args)
+    {
+        string sutRoot = "EG-BIM Modeler";
+        string outDir = Path.Combine("docs", "engine-catalog");
+
+        for (int i = 0; i < args.Length; i++)
+        {
+            switch (args[i])
+            {
+                case "--sut" when i + 1 < args.Length:
+                    sutRoot = args[++i];
+                    break;
+                case "--out" when i + 1 < args.Length:
+                    outDir = args[++i];
+                    break;
+            }
+        }
+
+        if (!Directory.Exists(sutRoot))
+        {
+            Console.Error.WriteLine($"SUT path not found: {sutRoot}");
+            return 2;
+        }
+
+        var assemblyNames = ResolveAssemblyNames(sutRoot);
+        Console.WriteLine($"Loading {assemblyNames.Count} assemblies from {sutRoot}");
+
+        using var loader = new MetadataLoader(sutRoot);
+        var types = loader.LoadTypes(assemblyNames).ToList();
+
+        var byAsm = types
+            .GroupBy(t => t.Assembly.GetName().Name ?? "?")
+            .OrderBy(g => g.Key, StringComparer.Ordinal);
+        foreach (var g in byAsm)
+        {
+            Console.WriteLine($"  {g.Key}: {g.Count()} types");
+        }
+
+        var candidates = CandidateFinder.Find(types);
+        var byCat = candidates
+            .GroupBy(c => c.Category)
+            .OrderBy(g => g.Key, StringComparer.Ordinal);
+        Console.WriteLine("Candidate categories:");
+        foreach (var g in byCat)
+        {
+            Console.WriteLine($"  {g.Key}: {g.Count()}");
+        }
+
+        var typesPath = Path.Combine(outDir, "hmeg-types.json").Replace('\\', '/');
+        var candPath = Path.Combine(outDir, "hmeg-candidates.json").Replace('\\', '/');
+        CatalogWriter.WriteTypes(typesPath, types);
+        CatalogWriter.WriteCandidates(candPath, candidates);
+        Console.WriteLine($"Wrote {typesPath}");
+        Console.WriteLine($"Wrote {candPath}");
+        return 0;
+    }
+
+    private static List<string> ResolveAssemblyNames(string sutRoot)
+    {
+        var set = new SortedSet<string>(StringComparer.Ordinal);
+        foreach (var pat in DefaultAssemblyPatterns)
+        {
+            foreach (var f in Directory.EnumerateFiles(sutRoot, pat, SearchOption.TopDirectoryOnly))
+            {
+                set.Add(Path.GetFileName(f));
+            }
+        }
+        return set.ToList();
+    }
+}
--- a/src/Recordingtest.EngineBridge.Probe/Recordingtest.EngineBridge.Probe.csproj
+++ b/src/Recordingtest.EngineBridge.Probe/Recordingtest.EngineBridge.Probe.csproj
@@ -0,0 +1,10 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <AssemblyName>Recordingtest.EngineBridge.Probe</AssemblyName>
+    <RootNamespace>Recordingtest.EngineBridge.Probe</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\Recordingtest.EngineBridge\Recordingtest.EngineBridge.csproj" />
+  </ItemGroup>
+</Project>
--- a/src/Recordingtest.EngineBridge/CandidateFinder.cs
+++ b/src/Recordingtest.EngineBridge/CandidateFinder.cs
@@ -0,0 +1,130 @@
+using System.Reflection;
+using System.Text;
+
+namespace Recordingtest.EngineBridge;
+
+public sealed record Candidate(
+    string Category,
+    string Assembly,
+    string TypeName,
+    string MemberKind,
+    string MemberName,
+    string Signature);
+
+public static class CandidateFinder
+{
+    private static readonly (string Category, string[] Keywords)[] Categories =
+    {
+        ("select", new[] { "Selection", "Selected", "Picked", "Pick" }),
+        ("camera", new[] { "Camera", "Viewport", "EyePoint", "LookAt", "View" }),
+        ("scene",  new[] { "Scene", "Document", "World", "Root" }),
+        ("render", new[] { "Render", "Draw", "Frame", "Dirty" }),
+    };
+
+    public static IReadOnlyList<Candidate> Find(IEnumerable<TypeInfo> types)
+    {
+        var results = new List<Candidate>();
+
+        foreach (var type in types)
+        {
+            var typeName = type.FullName ?? type.Name;
+            var asmName = type.Assembly.GetName().Name ?? "?";
+
+            foreach (var (category, keywords) in Categories)
+            {
+                bool typeMatches = keywords.Any(k =>
+                    typeName.Contains(k, StringComparison.OrdinalIgnoreCase));
+
+                // Properties
+                PropertyInfo[] props;
+                try { props = type.GetProperties(BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly); }
+                catch { props = Array.Empty<PropertyInfo>(); }
+                foreach (var p in props)
+                {
+                    if (typeMatches || keywords.Any(k => p.Name.Contains(k, StringComparison.OrdinalIgnoreCase)))
+                    {
+                        results.Add(new Candidate(
+                            category, asmName, typeName, "Property", p.Name,
+                            SafePropertySignature(p)));
+                    }
+                }
+
+                // Methods
+                MethodInfo[] methods;
+                try { methods = type.GetMethods(BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly); }
+                catch { methods = Array.Empty<MethodInfo>(); }
+                foreach (var m in methods)
+                {
+                    if (m.IsSpecialName) continue; // skip property/event accessors
+                    if (typeMatches || keywords.Any(k => m.Name.Contains(k, StringComparison.OrdinalIgnoreCase)))
+                    {
+                        results.Add(new Candidate(
+                            category, asmName, typeName, "Method", m.Name,
+                            SafeMethodSignature(m)));
+                    }
+                }
+
+                // Events
+                EventInfo[] events;
+                try { events = type.GetEvents(BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly); }
+                catch { events = Array.Empty<EventInfo>(); }
+                foreach (var e in events)
+                {
+                    if (typeMatches || keywords.Any(k => e.Name.Contains(k, StringComparison.OrdinalIgnoreCase)))
+                    {
+                        results.Add(new Candidate(
+                            category, asmName, typeName, "Event", e.Name,
+                            SafeEventSignature(e)));
+                    }
+                }
+            }
+        }
+
+        // Dedupe + sort deterministically.
+        return results
+            .Distinct()
+            .OrderBy(c => c.Category, StringComparer.Ordinal)
+            .ThenBy(c => c.Assembly, StringComparer.Ordinal)
+            .ThenBy(c => c.TypeName, StringComparer.Ordinal)
+            .ThenBy(c => c.MemberKind, StringComparer.Ordinal)
+            .ThenBy(c => c.MemberName, StringComparer.Ordinal)
+            .ThenBy(c => c.Signature, StringComparer.Ordinal)
+            .ToList();
+    }
+
+    private static string SafePropertySignature(PropertyInfo p)
+    {
+        try { return $"{SafeTypeName(p.PropertyType)} {p.Name} {{ {(p.CanRead ? "get;" : "")}{(p.CanWrite ? " set;" : "")} }}"; }
+        catch { return p.Name; }
+    }
+
+    private static string SafeMethodSignature(MethodInfo m)
+    {
+        try
+        {
+            var sb = new StringBuilder();
+            sb.Append(SafeTypeName(m.ReturnType)).Append(' ').Append(m.Name).Append('(');
+            var ps = m.GetParameters();
+            for (int i = 0; i < ps.Length; i++)
+            {
+                if (i > 0) sb.Append(", ");
+                sb.Append(SafeTypeName(ps[i].ParameterType)).Append(' ').Append(ps[i].Name ?? $"arg{i}");
+            }
+            sb.Append(')');
+            return sb.ToString();
+        }
+        catch { return m.Name; }
+    }
+
+    private static string SafeEventSignature(EventInfo e)
+    {
+        try { return $"{SafeTypeName(e.EventHandlerType ?? typeof(object))} {e.Name}"; }
+        catch { return e.Name; }
+    }
+
+    private static string SafeTypeName(Type t)
+    {
+        try { return t.FullName ?? t.Name; }
+        catch { return "?"; }
+    }
+}
--- a/src/Recordingtest.EngineBridge/CatalogWriter.cs
+++ b/src/Recordingtest.EngineBridge/CatalogWriter.cs
@@ -0,0 +1,59 @@
+using System.Reflection;
+using System.Text.Json;
+
+namespace Recordingtest.EngineBridge;
+
+public sealed record TypeEntry(string Assembly, string TypeName, bool IsPublic, string Namespace);
+
+public static class CatalogWriter
+{
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        WriteIndented = true,
+    };
+
+    public static IReadOnlyList<TypeEntry> BuildTypeEntries(IEnumerable<TypeInfo> types)
+    {
+        var list = new List<TypeEntry>();
+        foreach (var t in types)
+        {
+            var asm = t.Assembly.GetName().Name ?? "?";
+            var ns = t.Namespace ?? string.Empty;
+            var name = t.FullName ?? t.Name;
+            list.Add(new TypeEntry(asm, name, t.IsPublic, ns));
+        }
+        return list
+            .Distinct()
+            .OrderBy(e => e.Assembly, StringComparer.Ordinal)
+            .ThenBy(e => e.TypeName, StringComparer.Ordinal)
+            .ToList();
+    }
+
+    public static void WriteTypes(string path, IEnumerable<TypeInfo> types)
+    {
+        var entries = BuildTypeEntries(types);
+        WriteJson(path, entries);
+    }
+
+    public static void WriteCandidates(string path, IReadOnlyList<Candidate> candidates)
+    {
+        var sorted = candidates
+            .OrderBy(c => c.Category, StringComparer.Ordinal)
+            .ThenBy(c => c.Assembly, StringComparer.Ordinal)
+            .ThenBy(c => c.TypeName, StringComparer.Ordinal)
+            .ThenBy(c => c.MemberKind, StringComparer.Ordinal)
+            .ThenBy(c => c.MemberName, StringComparer.Ordinal)
+            .ThenBy(c => c.Signature, StringComparer.Ordinal)
+            .ToList();
+        WriteJson(path, sorted);
+    }
+
+    private static void WriteJson<T>(string path, T value)
+    {
+        var dir = Path.GetDirectoryName(Path.GetFullPath(path));
+        if (!string.IsNullOrEmpty(dir)) Directory.CreateDirectory(dir);
+        // Normalize forward-slash line endings + trailing newline for determinism.
+        var json = JsonSerializer.Serialize(value, JsonOptions).Replace("\r\n", "\n") + "\n";
+        File.WriteAllText(path, json);
+    }
+}
--- a/src/Recordingtest.EngineBridge/HmEgSnapshot.cs
+++ b/src/Recordingtest.EngineBridge/HmEgSnapshot.cs
@@ -0,0 +1,30 @@
+namespace Recordingtest.EngineBridge;
+
+/// <summary>
+/// Skeleton implementation of <see cref="IEngineSnapshot"/> for HmEG.
+/// Runtime probe is deferred to v2; all members throw NotImplementedException.
+/// The constants below mark the reflection anchor points that PoC v2 will
+/// bind to. The generator-time static catalog (see <see cref="CandidateFinder"/>)
+/// cross-checks that these names exist in the real SUT assemblies.
+/// </summary>
+public sealed class HmEgSnapshot : IEngineSnapshot
+{
+    public const string HmEgAssemblyHint = "HmEG";
+    public const string EditorManagerTypeHint = "HmEGAppManager";
+    public const string SelectionTypeHint = "Selection";
+    public const string CameraTypeHint = "Camera";
+    public const string SceneTypeHint = "Scene";
+    public const string RenderTypeHint = "Render";
+
+    public IReadOnlyList<string> SelectedObjectIds
+        => throw new NotImplementedException("Runtime probe deferred to v2");
+
+    public CameraState Camera
+        => throw new NotImplementedException("Runtime probe deferred to v2");
+
+    public SceneSummary Scene
+        => throw new NotImplementedException("Runtime probe deferred to v2");
+
+    public bool IsRenderComplete
+        => throw new NotImplementedException("Runtime probe deferred to v2");
+}
--- a/src/Recordingtest.EngineBridge/IEngineSnapshot.cs
+++ b/src/Recordingtest.EngineBridge/IEngineSnapshot.cs
@@ -0,0 +1,13 @@
+namespace Recordingtest.EngineBridge;
+
+public interface IEngineSnapshot
+{
+    IReadOnlyList<string> SelectedObjectIds { get; }
+    CameraState Camera { get; }
+    SceneSummary Scene { get; }
+    bool IsRenderComplete { get; }
+}
+
+public sealed record CameraState(double[] EyePoint, double[] Target, double[] Up, double Fov);
+
+public sealed record SceneSummary(int ObjectCount, string? DocumentPath);
--- a/src/Recordingtest.EngineBridge/MetadataLoader.cs
+++ b/src/Recordingtest.EngineBridge/MetadataLoader.cs
@@ -0,0 +1,73 @@
+using System.Reflection;
+using System.Runtime.InteropServices;
+
+namespace Recordingtest.EngineBridge;
+
+/// <summary>
+/// Thin wrapper around <see cref="MetadataLoadContext"/>. This class is
+/// metadata-only: it never invokes any static constructor or user code from
+/// the loaded assemblies. See the MetadataLoadContext documentation:
+/// https://learn.microsoft.com/dotnet/api/system.reflection.metadataloadcontext.
+/// </summary>
+public sealed class MetadataLoader : IDisposable
+{
+    private readonly MetadataLoadContext _mlc;
+    private readonly string _sutRoot;
+
+    public MetadataLoader(string sutRoot)
+    {
+        if (string.IsNullOrWhiteSpace(sutRoot)) throw new ArgumentException("sutRoot required", nameof(sutRoot));
+        _sutRoot = Path.GetFullPath(sutRoot);
+
+        var runtimeDir = RuntimeEnvironment.GetRuntimeDirectory();
+        var paths = new List<string>();
+        if (Directory.Exists(_sutRoot))
+        {
+            paths.AddRange(Directory.EnumerateFiles(_sutRoot, "*.dll", SearchOption.TopDirectoryOnly));
+        }
+        if (Directory.Exists(runtimeDir))
+        {
+            paths.AddRange(Directory.EnumerateFiles(runtimeDir, "*.dll", SearchOption.TopDirectoryOnly));
+        }
+
+        var resolver = new PathAssemblyResolver(paths);
+        _mlc = new MetadataLoadContext(resolver);
+    }
+
+    public IEnumerable<TypeInfo> LoadTypes(IEnumerable<string> assemblyFileNames)
+    {
+        foreach (var name in assemblyFileNames.OrderBy(n => n, StringComparer.Ordinal))
+        {
+            var path = Path.Combine(_sutRoot, name);
+            if (!File.Exists(path)) continue;
+
+            Assembly asm;
+            try
+            {
+                asm = _mlc.LoadFromAssemblyPath(path);
+            }
+            catch (Exception)
+            {
+                // Unreadable assembly — skip.
+                continue;
+            }
+
+            TypeInfo[] types;
+            try
+            {
+                types = asm.DefinedTypes.ToArray();
+            }
+            catch (ReflectionTypeLoadException rtle)
+            {
+                types = rtle.Types.Where(t => t != null).Select(t => t!.GetTypeInfo()).ToArray();
+            }
+
+            foreach (var t in types)
+            {
+                yield return t;
+            }
+        }
+    }
+
+    public void Dispose() => _mlc.Dispose();
+}
--- a/src/Recordingtest.EngineBridge/Recordingtest.EngineBridge.csproj
+++ b/src/Recordingtest.EngineBridge/Recordingtest.EngineBridge.csproj
@@ -0,0 +1,10 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <AssemblyName>Recordingtest.EngineBridge</AssemblyName>
+    <RootNamespace>Recordingtest.EngineBridge</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="System.Reflection.MetadataLoadContext" Version="8.0.0" />
+    <PackageReference Include="System.Text.Json" Version="8.0.5" />
+  </ItemGroup>
+</Project>
--- a/tests/Recordingtest.EngineBridge.Tests/EngineBridgeTests.cs
+++ b/tests/Recordingtest.EngineBridge.Tests/EngineBridgeTests.cs
@@ -0,0 +1,135 @@
+using System.Reflection;
+using System.Text.Json;
+using Recordingtest.EngineBridge;
+using Xunit;
+
+namespace Recordingtest.EngineBridge.Tests;
+
+public sealed class EngineBridgeTests
+{
+    private static readonly Lazy<string?> SutRootLazy = new(FindSutRoot);
+    private static string? SutRoot => SutRootLazy.Value;
+    private static bool SutAvailable => SutRoot != null;
+
+    private static readonly string[] TargetAssemblies =
+    {
+        "HmEG.dll",
+        "HmGeometry.dll",
+        "HmGeometry.V2.dll",
+        "HmTriangle.dll",
+        "EditorCore.dll",
+        "Editor02.HmEGAppManager.dll",
+        "Editor03.PluginInterface.dll",
+    };
+
+    private static string? FindSutRoot()
+    {
+        var dir = new DirectoryInfo(AppContext.BaseDirectory);
+        for (int i = 0; i < 10 && dir != null; i++)
+        {
+            var candidate = Path.Combine(dir.FullName, "EG-BIM Modeler");
+            if (Directory.Exists(candidate) && File.Exists(Path.Combine(candidate, "HmEG.dll")))
+                return candidate;
+            dir = dir.Parent;
+        }
+        return null;
+    }
+
+    [Fact]
+    public void MetadataLoader_LoadsHmegAssembly_WithoutExecution()
+    {
+        if (!SutAvailable) { Assert.True(true, "SUT not available — skipped"); return; }
+
+        // MetadataLoadContext is pure metadata: it never runs type initializers
+        // or any user code from the loaded assembly. The fact that we can load
+        // HmEG.dll (which would otherwise need SharpDX/WPF at runtime) and
+        // enumerate DefinedTypes without a TypeInitializationException is the
+        // observable evidence of that guarantee.
+        using var loader = new MetadataLoader(SutRoot!);
+        var types = loader.LoadTypes(new[] { "HmEG.dll" }).ToList();
+        Assert.True(types.Count > 0);
+    }
+
+    [Fact]
+    public void CandidateFinder_FindsSelectionRelatedTypes()
+    {
+        if (!SutAvailable) { Assert.True(true, "SUT not available — skipped"); return; }
+
+        using var loader = new MetadataLoader(SutRoot!);
+        var types = loader.LoadTypes(TargetAssemblies).ToList();
+        var candidates = CandidateFinder.Find(types);
+        Assert.Contains(candidates, c => c.Category == "select");
+    }
+
+    [Fact]
+    public void CatalogSerializer_OutputsSorted_Idempotent()
+    {
+        if (!SutAvailable) { Assert.True(true, "SUT not available — skipped"); return; }
+
+        using var loader = new MetadataLoader(SutRoot!);
+        var types = loader.LoadTypes(new[] { "HmEG.dll" }).ToList();
+        var candidates = CandidateFinder.Find(types);
+
+        var tmp1 = Path.Combine(Path.GetTempPath(), "eb-cand-1-" + Guid.NewGuid().ToString("N") + ".json");
+        var tmp2 = Path.Combine(Path.GetTempPath(), "eb-cand-2-" + Guid.NewGuid().ToString("N") + ".json");
+        try
+        {
+            CatalogWriter.WriteCandidates(tmp1, candidates);
+            CatalogWriter.WriteCandidates(tmp2, candidates);
+            Assert.Equal(File.ReadAllBytes(tmp1), File.ReadAllBytes(tmp2));
+        }
+        finally
+        {
+            File.Delete(tmp1);
+            File.Delete(tmp2);
+        }
+    }
+
+    [Fact]
+    public void HmEgSnapshot_DefaultInstance_ThrowsNotImplemented()
+    {
+        var s = new HmEgSnapshot();
+        Assert.Throws<NotImplementedException>(() => _ = s.SelectedObjectIds);
+        Assert.Throws<NotImplementedException>(() => _ = s.Camera);
+        Assert.Throws<NotImplementedException>(() => _ = s.Scene);
+        Assert.Throws<NotImplementedException>(() => _ = s.IsRenderComplete);
+    }
+
+    [Fact]
+    public void CandidateCategories_AllFourPresent()
+    {
+        if (!SutAvailable) { Assert.True(true, "SUT not available — skipped"); return; }
+
+        using var loader = new MetadataLoader(SutRoot!);
+        var types = loader.LoadTypes(TargetAssemblies).ToList();
+        var candidates = CandidateFinder.Find(types);
+
+        foreach (var cat in new[] { "select", "camera", "scene", "render" })
+        {
+            Assert.True(candidates.Any(c => c.Category == cat), $"category '{cat}' missing");
+        }
+    }
+
+    [Fact]
+    public void HmEgSnapshot_Constants_MatchCatalog()
+    {
+        if (!SutAvailable) { Assert.True(true, "SUT not available — skipped"); return; }
+
+        using var loader = new MetadataLoader(SutRoot!);
+        var types = loader.LoadTypes(TargetAssemblies).ToList();
+        var candidates = CandidateFinder.Find(types);
+
+        // HmEgAssemblyHint ("HmEG") should be a prefix of at least one loaded assembly.
+        var asmNames = types.Select(t => t.Assembly.GetName().Name ?? "").Distinct().ToList();
+        Assert.Contains(asmNames, a => a.StartsWith(HmEgSnapshot.HmEgAssemblyHint, StringComparison.Ordinal));
+
+        // EditorManagerTypeHint ("HmEGAppManager") should appear in at least one candidate TypeName OR type entry.
+        var appearsInCandidates = candidates.Any(c =>
+            c.TypeName.Contains(HmEgSnapshot.EditorManagerTypeHint, StringComparison.Ordinal));
+        var appearsInTypes = types.Any(t =>
+            (t.FullName ?? t.Name).Contains(HmEgSnapshot.EditorManagerTypeHint, StringComparison.Ordinal) ||
+            (t.Assembly.GetName().Name ?? "").Contains(HmEgSnapshot.EditorManagerTypeHint, StringComparison.Ordinal));
+        Assert.True(appearsInCandidates || appearsInTypes,
+            $"EditorManagerTypeHint '{HmEgSnapshot.EditorManagerTypeHint}' not found in catalog");
+    }
+}
--- a/tests/Recordingtest.EngineBridge.Tests/Recordingtest.EngineBridge.Tests.csproj
+++ b/tests/Recordingtest.EngineBridge.Tests/Recordingtest.EngineBridge.Tests.csproj
@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <IsPackable>false</IsPackable>
+    <RootNamespace>Recordingtest.EngineBridge.Tests</RootNamespace>
+    <AssemblyName>Recordingtest.EngineBridge.Tests</AssemblyName>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageReference Include="xunit" Version="2.9.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Recordingtest.EngineBridge\Recordingtest.EngineBridge.csproj" />
+  </ItemGroup>
+</Project>