C API Extend

Extending the YSE C API for new engine surface

YseEngine/c_api/ is the only entry point for FFI consumers (Dart, Python, …). The C API has explicit rules — RT-safe callback bridges, opaque-handle ownership, null-safe no-op semantics, YSE_C_CALLBACK ABI defence, exception-to-YseStatus translation, enum drift guard — that the engine's own public C++ API does not enforce. New wrapping must follow all of them; a careless callback bridge can stall the audio thread.

This skill governs how to wrap new engine surface in the C API. Read it fully before editing any file under YseEngine/c_api/.

Issue tracking — GitHub Issues first

CLAUDE.md mandates an issue before code. For this skill:

• File the issue first with gh issue create --title "c-api: ...". Use the enhancement or task template; tag the layer as c-api.
• Branch from dev as <issue-number>-c-api-<short-slug> and PR back to dev. Not master — see CLAUDE.md §1.
• Read context with gh issue view <n> before starting if the request mentions an existing issue number.

The gh CLI is authenticated in the project environment.

When to invoke this skill

Yes:

• A new engine class / method / enum was added and needs C-ABI exposure.
• The user asks to audit the C API for drift from the engine.
• The user is starting a new C-API wrapping pass (e.g. a sub-issue of a C API audit epic such as #898).

No:

• Modifying behaviour of an existing C-API function without adding surface — that's a regular fix, use the normal workflow.
• Internal engine refactors that don't change the public C++ surface.
• Adding audio-thread-reachable callbacks (dspSourceObject user callback, customFileReader) on a casual wrapping pass. Those need design work — see the "Callback bridge rules" block in yse_c_internal.hpp.

The six conventions

Every new C-API entry point must respect all six.

1. Opaque handle shape and ownership

Each engine type that gets a C handle is declared with typedef struct YseFoo YseFoo; and accessed only via YseFoo* pointers. The .cpp file does reinterpret_cast<YSE::foo*>(handle). Never expose any C++ type, class, namespace, reference, or template across the C ABI.

Every typedef in its home header carries a one-line ownership comment:

/* Owned — release with yse_foo_destroy. */
typedef struct YseFoo YseFoo;

/* Borrowed singleton — owned by the engine, never destroy.
   Obtain via yse_foo_get(). */
typedef struct YseFoo YseFoo;

/* Borrowed — owned by parent YsePatcher. Release with
   yse_patcher_delete_object(patcher, handle); never call a destroy on
   the handle directly. */
typedef struct YsePHandle YsePHandle;

Dual-shape types (e.g. YseChannel is owned via yse_channel_create but borrowed via the pre-built accessors) get both lines.

Forward-declaration typedefs (in headers that don't own the type) point the reader at the home header rather than duplicating the ownership note:

/* Forward declarations — see yse_channel.h / yse_dsp.h for ownership. */
typedef struct YseChannel YseChannel;
typedef struct YseDspBuffer YseDspBuffer;

Every handle typedef — home header and forward declaration alike — sits behind its own YSE_C_HANDLE_<Type> guard (#976), because repeating a typedef is a C11 feature and the headers must stay C99-clean:

#ifndef YSE_C_HANDLE_YseFoo
#define YSE_C_HANDLE_YseFoo
/** Owned — release with yse_foo_destroy. */
typedef struct YseFoo YseFoo;
#endif

Keep the comment inside the guard, directly above the typedef: placed above the #ifndef, Doxygen attaches it to the #define instead, and the Sphinx build fails on the duplicated macro.

The yse_c99_header_check object library in Tests/CMakeLists.txt compiles every public header as -std=c99 -pedantic-errors, so an unguarded typedef fails the test build.

Canonical examples: yse_patcher.h (owned + borrowed pair), yse_reverb.h (dual-shape).

2. Header layout

Every include/yse_c/yse_<module>.h:

• Top-of-file block comment naming purpose, the mirrored engine source, scope notes, and the null-safe-no-op convention statement.
• #ifndef / #define / #endif include guards. No #pragma once.
• #include "yse_common.h" (and yse_enums.h if needed) — never an engine C++ header.
• #ifdef __cplusplus / extern "C" { ... } / #endif wraps the body.
• YSE_C_API on every exported function declaration.
• YSE_C_CALLBACK on every callback typedef, named Yse<Module><What>Callback in PascalCase (YseBusTapCallback, YseScriptErrorCallback, YsePatcherSendCallback) — never a lowercase yse_*_cb (#911 renamed the last of those).
• Functions carry their header's module prefix: yse_<module>_... (yse_python_run_script, not yse_run_script).
• General-purpose helpers live in yse_common.h (yse_last_error, yse_free_string for library-allocated strings), not in whichever module first needed them.
• All booleans as int (0/1), never bool. All sizes as size_t or unsigned int. Strings as const char* (in) or char* + size_t (snprintf-style out).

Canonical example: yse_sound.h.

3. Function shape

The header-top convention paragraph captures the void-no-op rule once for the whole header. Per-function comments are reserved for genuinely surprising behaviour.

Body pattern for fallible operations (lift from yse_sound.cpp):

YSE_C_API YseStatus yse_x_load(YseX* h, const char* arg) {
  if (!h) return YSE_ERR_INVALID_HANDLE;
  if (!arg) return YSE_ERR_INVALID_ARGUMENT;
  try {
    if (!to_cpp(h)->load(arg)) {
      yse_c::set_last_error(std::string("x load failed for: ") + arg);
      return YSE_ERR_<specific>;
    }
    return YSE_OK;
  } catch (const std::exception& e) {
    yse_c::set_last_error(e.what());
    return YSE_ERR_EXCEPTION;
  } catch (...) {
    yse_c::set_last_error("yse_x_load: unknown C++ exception");
    return YSE_ERR_EXCEPTION;
  }
}

Body pattern for void state-change:

YSE_C_API void yse_x_play(YseX* h) { if (h) to_cpp(h)->play(); }

Body pattern for string-out:

YSE_C_API size_t yse_x_get_name(YseX* h, char* buf, size_t cap) {
  if (!h) { if (buf && cap > 0) buf[0] = '\0'; return 0; }
  return copy_string(to_cpp(h)->getName(), buf, cap);
}

Canonical example for the snprintf pattern: yse_device.cpp.

4. Callback bridges — RT-safe shape

When the engine invokes a user-provided callback on a non-host thread (audio callback, RtMidi input thread, file streaming worker, the control-thread occlusion driver, future dspSourceObject / customFileReader paths), the bridge:

1. Holds the callback + user_data as one immutable pair node behind a single std::atomic<Pair*> — never two separate atomics, which let a dispatch between the two stores of a re-install pair one install's cb with another's user_data (#902, #916). Never std::mutex or std::lock_guard on the dispatch path.
2. Installs by allocating the new pair (inside the ABI exception barrier) and publishing it with one atomic exchange.
3. Dispatches by loading the pointer once (return if null) and reading cb and user_data from that same node. The replaced node is freed only after a named grace period proves no dispatch still reads it: the log bridge waits for the sink mutex every dispatch runs under; the MIDI raw bridge uses a seq_cst reader-count handshake around the pointer load, with no user code inside the window the installer waits on. A straight passthrough to an engine setter is fine only when that setter keeps the pair as one node itself (YSE::midiIn's raw / parsed setters do since #917); still wrap the install in the exception barrier.
4. Does not malloc / new / construct std::string on dispatch when the bridge can fire from the audio callback. For raw byte buffers needed by an async-Dart host, preallocate a per-handle pool keyed by the handle.
5. Uses YSE_C_CALLBACK on the typedef.
6. If the bridge transfers heap ownership to the host (Dart's NativeCallable.listener requires this), pair the callback with a yse_<module>_free_message function and document the contract beside the typedef.

Canonical examples:

• yse_midi.cpp — c_raw_bridge, pair-pointer swap reclaimed by a reader-count handshake; malloc per call is acceptable because the RtMidi input thread is not the audio callback.
• yse_log.cpp — CallbackBridge, same pair-pointer swap reclaimed behind the log sink mutex, same Dart-ownership malloc.

The "Callback bridge rules" block at the head of yse_c_internal.hpp restates these rules in detail. Read it before designing any new bridge.

5. Enum mirroring + drift guard

When the engine adds an enum value that should be visible from the C API:

1. Add a matching Yse<Name>_<VALUE> entry to yse_enums.h. Mirror the integer value exactly. Use C-compatible typedef enum {...} Yse<Name>; syntax (not enum class).
2. Add a YSE_ASSERT_ENUM(YSE_..., YSE::...); line to yse_enums_check.cpp. The build fails loudly if the values drift.

If the engine adds a brand-new enum, add the full mirror block + a full set of YSE_ASSERT_ENUM lines. The drift guard is the only safety net for the hand-mirrored file.