MpsBuilder

──────────────────────────────────────────────────────────────────── Class-form facade (Phase B of the compile OOP refactor) ────────────────────────────────────────────────────────────────────

MpsBuilder is the OOP shape behind the 5 compile_* free functions above. Each free function above is now a thin forwarder that constructs a transient MpsBuilder and dispatches to the matching method. The free-function signatures are preserved for binding stability — Python (and the cache) still import them by name.

Lifetime. One MpsBuilder per compile call. The class owns:

• Reference to the TraceGraph and external_feeds map.
• The in-progress MPSGraph* (held as void* in this pure-C++ header; the .mm re-casts via __bridge).
• The BuilderContext that emitters write into.
• A scratch std::string* error_msg pointer for failure reporting; populated on failure return.

Construction. The constructor takes the same three arguments shared by every public method: graph, external_feeds, and the optional error_msg. It does not do any MPSGraph work — the MPSGraph is created lazily inside each compile_<mode> method. This keeps construction lightweight (the free-function forwarders create an instance even when validation rejects the call) and avoids leaking an MPSGraph allocation on early-exit paths.

Why a class rather than 5 free functions. The 5 functions shared ~60% scaffolding expressed as copy-paste (device check, emitter precheck, placeholder creation, emit loop, target construction, MPSGraph compile). Grouping them as methods on a shared class lets future shared-scaffolding refactors land in one place rather than in 5 lock-stepped diffs. The 5 methods intentionally remain as distinct entry points rather than virtual dispatch — the divergence between forward-only / forward-bwd / fused-step / generic-fused-step / variables is finite-state, not hierarchical.