capi: list-valued request options

docs/c_api.md

@@ -71,6 +71,33 @@ if ((audiocpp_abi_version() >> 16) != AUDIOCPP_ABI_VERSION_MAJOR) {
 }
 ```
 
+**minor** increments when entry points are added. Nothing is removed or changed
+by such a release, so a caller built against a lower minor keeps working
+untouched — but a caller that needs a newer entry point can say so, which is
+the only reason the field carries information:
+
+```c
+/* audiocpp_request_set_option_array arrived in 0.2. */
+if ((audiocpp_abi_version() & 0xffff) < 0x0200) {
+    /* fall back, or refuse, rather than resolving a symbol that is not there */
+}
+```
+
+A C caller can also just resolve the symbol and test for NULL, which is exact
+and needs no number at all. The version is for the callers that cannot: a
+binding that declares its imports up front — C#, JNA, ctypes with prototypes —
+binds on first use and raises a missing-symbol error from inside the call, which
+is a poor way to discover that a library is too old.
+
+**patch** is for behaviour fixes that add and change no surface. Do not gate on
+it; it tells a caller nothing about what it may call.
+
+⚠ `0.1` covers two different surfaces. The four entry points added in #544
+(`audiocpp_task_count`, `audiocpp_task_name`, `audiocpp_task_from_spec_name`,
+`audiocpp_request_set_text_language`) shipped without a bump, before this rule
+existed, so a library reporting `0.1` may or may not have them. From `0.2`
+onward the minor is the answer.
+
 ## Usage
 
 ```c

include/audiocpp.h

@@ -51,11 +51,14 @@ extern "C" {
 /* ------------------------------------------------------------------ */
 
 #define AUDIOCPP_ABI_VERSION_MAJOR 0
-#define AUDIOCPP_ABI_VERSION_MINOR 1
+#define AUDIOCPP_ABI_VERSION_MINOR 2
 #define AUDIOCPP_ABI_VERSION_PATCH 0
 
 /* Packed as (major << 16) | (minor << 8) | patch. A caller built against a
- * different MAJOR must not use the library. */
+ * different MAJOR must not use the library. MINOR increments when entry points
+ * are added -- nothing is removed or changed -- so a caller needing a newer one
+ * can require a minimum; PATCH is behaviour only and must not be gated on. See
+ * docs/c_api.md. */
 AUDIOCPP_API uint32_t audiocpp_abi_version(void);
 
 /* audio.cpp's own build version, e.g. "0.2.1". Borrowed, static lifetime. */
@@ -370,6 +373,21 @@ AUDIOCPP_API audiocpp_status audiocpp_request_set_option(audiocpp_request * requ
                                                          const char * key,
                                                          const char * value);
 
+/* Sets a list-valued request option -- the transport for the `*_list` option
+ * types the model spec already declares. `values` is `count` UTF-8 strings,
+ * copied into the request, so neither the array nor the strings need outlive
+ * the call. A second call with the same key REPLACES the list rather than
+ * appending, matching set_option's assignment semantics.
+ *
+ * List options live in their own map, so a key set here is not visible to a
+ * family reading single-valued options and vice versa; a family declares which
+ * one it wants by the type it puts in its spec. `count` may be 0, which sets an
+ * empty list -- distinct from never setting the key at all. */
+AUDIOCPP_API audiocpp_status audiocpp_request_set_option_array(audiocpp_request * request,
+                                                               const char * key,
+                                                               const char * const * values,
+                                                               size_t count);
+
 /* ------------------------------------------------------------------ */
 /* Result                                                              */
 /* ------------------------------------------------------------------ */

include/engine/framework/runtime/session.h

@@ -163,6 +163,10 @@ struct TaskRequest {
     std::optional<VoiceCondition> voice = std::nullopt;
     std::vector<VoiceArtifact> input_artifacts;
     std::unordered_map<std::string, std::string> options;
+    /// List-valued options, kept apart from the single-valued ones so a family
+    /// reading either cannot silently see the other half-formed. The `*_list`
+    /// option types the spec schema already declares are carried here.
+    std::unordered_map<std::string, std::vector<std::string>> option_arrays;
 };
 
 struct AudioPreparationContract {
@@ -176,6 +180,9 @@ struct SessionPreparationRequest {
     std::optional<Transcript> text = std::nullopt;
     std::optional<VoiceCondition> voice = std::nullopt;
     std::unordered_map<std::string, std::string> options;
+    /// See TaskRequest::option_arrays. Carried through preparation so a session
+    /// can size its graphs for what run() will actually be handed.
+    std::unordered_map<std::string, std::vector<std::string>> option_arrays;
 };
 
 struct VoiceActivityEvent {

include/engine/framework/runtime/spec_backed_model.h

@@ -11,6 +11,7 @@
 #include <memory>
 #include <stdexcept>
 #include <string>
+#include <vector>
 #include <string_view>
 #include <unordered_map>
 #include <utility>
@@ -67,6 +68,22 @@ inline void validate_spec_backed_request_options(
     }
 }
 
+/// The same check for list-valued options. An overload rather than a second
+/// name: a family that gained a list option should not have to remember to call
+/// something different, and every existing call site keeps working untouched.
+inline void validate_spec_backed_request_options(
+    const std::unordered_map<std::string, std::string> & options,
+    const std::unordered_map<std::string, std::vector<std::string>> & option_arrays,
+    const engine::model_spec::ModelContract & contract,
+    std::string_view model_name) {
+    validate_spec_backed_request_options(options, contract, model_name);
+    for (const auto & [key, _] : option_arrays) {
+        if (contract.request_option_keys.find(key) == contract.request_option_keys.end()) {
+            throw std::runtime_error("unknown " + std::string(model_name) + " request option: " + key);
+        }
+    }
+}
+
 inline std::unordered_map<std::string, std::string> apply_option_v1_compatibility(
     std::unordered_map<std::string, std::string> options,
     std::initializer_list<OptionV1CompatibilityAlias> aliases,

src/capi/audiocpp.cpp

@@ -830,6 +830,34 @@ audiocpp_status audiocpp_request_set_option(audiocpp_request * request, const ch
     });
 }
 
+audiocpp_status audiocpp_request_set_option_array(audiocpp_request * request,
+                                                  const char * key,
+                                                  const char * const * values,
+                                                  size_t count) {
+    if (request == nullptr || key == nullptr) {
+        return fail(AUDIOCPP_ERR_INVALID_ARGUMENT, "request and key must be non-null");
+    }
+    if (values == nullptr && count != 0) {
+        return fail(AUDIOCPP_ERR_INVALID_ARGUMENT, "values must be non-null when count is not 0");
+    }
+    for (size_t i = 0; i < count; ++i) {
+        // Checked before anything is written, so a bad element cannot leave the
+        // option half-assigned.
+        if (values[i] == nullptr) {
+            return fail(AUDIOCPP_ERR_INVALID_ARGUMENT, "option array values must be non-null");
+        }
+    }
+    return guard([&] {
+        std::vector<std::string> copied;
+        copied.reserve(count);
+        for (size_t i = 0; i < count; ++i) {
+            copied.emplace_back(values[i]);
+        }
+        request->request.option_arrays[key] = std::move(copied);
+        return AUDIOCPP_OK;
+    });
+}
+
 /* ------------------------------------------------------------------ */
 /* Result                                                              */
 /* ------------------------------------------------------------------ */

src/framework/runtime/session.cpp

@@ -432,6 +432,13 @@ SessionPreparationRequest build_preparation_request(const AudioBuffer & audio) {
 SessionPreparationRequest build_preparation_request(const TaskRequest & request) {
     SessionPreparationRequest prep;
     prep.options = request.options;
+    // ⚠ CARRY THE LIST OPTIONS TOO. Preparation decides how the graphs are sized, and a family
+    // whose work depends on a list option would otherwise size itself for a different request
+    // than the one run() is handed. For kokoro_tts that was not merely a bad estimate: with the
+    // phonemes missing here, preparation fell back to the built-in G2P, and a Japanese request
+    // failed for want of UniDic even though the caller had supplied phonemes precisely so that
+    // the G2P would never be consulted.
+    prep.option_arrays = request.option_arrays;
     prep.text = request.text_input;
     prep.voice = request.voice;
     if (request.audio_input.has_value()) {