recordingtest/docs/engine-bridge-probe-design.md

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