feat: add sprux_begin_capture/sprux_end_capture to C API

Expose MetalContext::beginCapture/endCapture through the C API so
embedders (JAX FFI, Python) can bracket GPU trace captures around
specific code sections, avoiding capturing JIT warmup noise.

Co-developed-by: Claude Code v2.1.81 (claude-opus-4-6)

Author: robtaylor

sprux/sprux/sprux_c_api.cpp

@@ -15,6 +15,10 @@
 #include "sprux/sprux/Solver.h"
 #include "sprux/sprux/SpruxFFISolver.h"
 
+#ifdef SPRUX_USE_METAL
+#include "sprux/sprux/MetalDefs.h"
+#endif
+
 using namespace Sprux;
 
 struct sprux_solver {
@@ -193,4 +197,26 @@ int sprux_ffi_dot(sprux_ffi_solver_t h, const double* csr_data, const double* x,
   }
 }
 
+int sprux_begin_capture(const char* output_path) {
+#ifdef SPRUX_USE_METAL
+  try {
+    return MetalContext::instance().beginCapture(output_path) ? 1 : 0;
+  } catch (...) {
+    return 0;
+  }
+#else
+  (void)output_path;
+  return 0;
+#endif
+}
+
+void sprux_end_capture(void) {
+#ifdef SPRUX_USE_METAL
+  try {
+    MetalContext::instance().endCapture();
+  } catch (...) {
+  }
+#endif
+}
+
 }  // extern "C"

sprux/sprux/sprux_c_api.h

@@ -197,6 +197,20 @@ int sprux_ffi_solve(sprux_ffi_solver_t h, const double* csr_data, const double*
  */
 int sprux_ffi_dot(sprux_ffi_solver_t h, const double* csr_data, const double* x, double* b_out);
 
+/**
+ * Begin a GPU trace capture. Writes a .gputrace file for analysis in
+ * Xcode or apple-profiler tools.
+ *
+ * @param output_path  Path for .gputrace output (e.g. "/tmp/sprux.gputrace")
+ * @return 1 if capture started, 0 if not (Metal not available or already capturing)
+ */
+int sprux_begin_capture(const char* output_path);
+
+/**
+ * End a GPU trace capture started with sprux_begin_capture.
+ */
+void sprux_end_capture(void);
+
 #ifdef __cplusplus
 }
 #endif