capi: list-valued request options

[christopherthompson81]

Review copy on the fork. Framework only — no model family is touched, and nothing uses this yet. The consumer is a separate PR.

It completes something already half-designed

The model spec has declared string_list / float_list / path_list / audio_path_list since schema v1, and schema.cpp validates their declarations — but nothing carries one at run time. Options are string -> string from the ABI down to TaskRequest::options, so a family wanting a list has no transport, and no spec has ever used the types.

AUDIOCPP_API audiocpp_status audiocpp_request_set_option_array(audiocpp_request * request,
                                                               const char * key,
                                                               const char * const * values,
                                                               size_t count);

• Values are copied; neither the array nor the strings need outlive the call.
• A second call with the same key replaces rather than appends, matching set_option.
• count == 0 sets an empty list — distinct from never setting the key.
• A null element is rejected before anything is written, so it cannot leave the option half-assigned.
• Lists live in their own map (TaskRequest::option_arrays), so a family reading single-valued options cannot see a half-formed list; which one it reads is declared by the type in its spec.
• validate_spec_backed_request_options gains an overload — an undeclared list key is rejected exactly as an undeclared scalar one is, and every existing call site is untouched.

⚠ build_preparation_request carries the new map too. Preparation decides how graphs are sized, so a family whose work depends on a list option would otherwise prepare against a different request than the one run() is handed — and, worse, fall back to whatever it does when the option is absent. That was not hypothetical: it cost a whole language in testing before it was caught.

ABI minor 1 → 2, and the minor now means that

It has never moved, including across 0xShug0#544, which added four entry points. A three-field version where two fields never change cannot answer the question a caller has.

Minor increments when entry points are added — nothing is removed or changed, so a caller built against a lower minor keeps working, and one that needs a newer entry point can require a minimum. Patch is behaviour-only and must not be gated on. docs/c_api.md says so now.

A C caller can of course resolve the symbol and test for NULL, which is exact and needs no version at all. The field is for the callers that cannot: a binding declaring 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 find out a library is too old.

⚠ Recorded rather than papered over: 0.1 covers two different surfaces, because 0xShug0#544's entry points shipped without a bump. From 0.2 the minor is the answer.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EkxqpYvUbjCpRDnFiNiVfx