@voxgig/sdkgen 4.5.3 → 4.7.0

package/project/.sdk/tm/js/test/feature/Corpus.test.js

@@ -84,7 +84,16 @@ function scriptedFetcher(res) {
 
 
 function makeClient(kase) {
+  // `test: { active: true }` is the OPTION, not the `test` FEATURE.
+  //
+  // It says "this client is not live", which is what makes a REQUIRED
+  // OpenAPI server variable resolve to a deterministic `test-<name>`
+  // rather than refuse to construct (see makeOptions). It installs no
+  // transport, so the scripted fetcher below still stands — the FEATURE
+  // is transport: 'base' and would shadow it, which is why this cannot
+  // just turn the feature on.
   return new SDK({
+    test: { active: true },
     feature: kase.feature,
     utility: { fetcher: scriptedFetcher(kase.res || [{ status: 200, body: {} }]) },
   })

package/project/.sdk/tm/js/test/sdk-test-control.json

@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "_doc": "Per-SDK test control. Lists tests/operations to skip in unit and live modes; tunes per-test pacing. Edit by hand. Loaded by js/test/utility.js.",
+  "test": {
+    "skip": {
+      "live": {
+        "direct": [],
+        "entityOp": []
+      },
+      "unit": {
+        "direct": [],
+        "entityOp": []
+      }
+    },
+    "live": {
+      "delayMs": 500
+    }
+  }
+}

package/project/.sdk/tm/js/test/utility.js

@@ -5,6 +5,10 @@
  * for creating test data, transformations, validations, and environment overrides.
  */
 
+const Fs = require('node:fs')
+const Path = require('node:path')
+
+
 // Creates a new step data structure within the data model
 function makeStepData(dm, stepname) {
   dm.s[stepname] = {
@@ -62,11 +66,97 @@ function envOverride(m) {
 }
 
 
+// Loads sdk-test-control.json (cached). Returns an empty-skip object if
+// the file is missing or unparsable so tests never crash on a bad config.
+let _testControlCache = null
+
+function loadTestControl() {
+  if (_testControlCache) return _testControlCache
+  const ctrlPath = Path.resolve(__dirname, '../test/sdk-test-control.json')
+  try {
+    _testControlCache = JSON.parse(Fs.readFileSync(ctrlPath, 'utf8'))
+  }
+  catch {
+    _testControlCache = {
+      version: 1,
+      test: { skip: { live: { direct: [], entityOp: [] }, unit: { direct: [], entityOp: [] } } }
+    }
+  }
+  return _testControlCache
+}
+
+
+// Extra SDK options every LIVE client is constructed with, read from
+// sdk-test-control.json `test.client.options`.
+//
+// The generated live client knows two things: the base URL (from the spec)
+// and the credential (from the environment). Everything else about how a
+// particular API wants to be talked to - which features to switch on, and
+// with what settings - is a property of THAT API, known to the project and
+// to nothing in the toolchain. So it lives in the file the project owns and
+// describes, where it can be read and reviewed. Secrets still come from the
+// environment (the providers this block names read them).
+//
+// Merged UNDER the generated fields, so the suite's own base/apikey/server
+// values win - this adds to the live client, it does not redirect it.
+//
+// That contract is enforced HERE rather than left to each merge site: the
+// generated object only names a field when the model calls for one, so a
+// `base` in this block would face no competing value and would silently
+// redirect the whole suite - credential included - to another host. The
+// reserved fields are stripped once, where the block is read, so every
+// caller gets the same guarantee whether or not it happens to emit them.
+const LIVE_RESERVED = ['base', 'prefix', 'suffix', 'server', 'apikey', 'secret']
+
+function liveClientOptions() {
+  const ctrl = loadTestControl()
+  const opts = ctrl && ctrl.test && ctrl.test.client && ctrl.test.client.options
+
+  if (null == opts || 'object' !== typeof opts) {
+    return {}
+  }
+
+  const out = {}
+  for (const key of Object.keys(opts)) {
+    if (!LIVE_RESERVED.includes(key)) {
+      out[key] = opts[key]
+    }
+  }
+
+  return out
+}
+
+
+// Per-test live pacing delay (ms). Read from sdk-test-control.json
+// `test.live.delayMs`; defaults to 500ms if absent or invalid.
+function liveDelayMs() {
+  const ctrl = loadTestControl()
+  const v = ctrl && ctrl.test && ctrl.test.live && ctrl.test.live.delayMs
+  return ('number' === typeof v && v >= 0) ? v : 500
+}
+
+
+
+// afterEach hook helper for live pacing. Generated tests register this via
+// `afterEach(liveDelay(<envVar>))`; it sleeps `liveDelayMs()` only when the
+// SDK's *_TEST_LIVE env var is set.
+function liveDelay(liveEnvVar) {
+  return async () => {
+    if ('TRUE' === process.env[liveEnvVar]) {
+      await new Promise(r => setTimeout(r, liveDelayMs()))
+    }
+  }
+}
+
 module.exports = {
   makeStepData,
   makeMatch,
   makeReqdata,
   makeValid,
   makeCtrl,
-  envOverride
+  envOverride,
+  loadTestControl,
+  liveClientOptions,
+  liveDelayMs,
+  liveDelay
 }

package/project/.sdk/tm/kotlin/utility/MakeOptions.kt

@@ -28,8 +28,24 @@ fun makeOptions(ctx: Context): MutableMap<String, Any?> {
     }
   }
 
+  // `auth: null` is the documented way to disable auth outright, and
+  // PrepareAuth honours it before it ever reads the apikey. It cannot survive
+  // validate: depending on the struct port a stored null is either REPLACED
+  // by the optspec default - transmitting the credential the caller withheld
+  // - or REJECTED outright. Withhold the key for validate, then put the null
+  // back. Same fix as ts/js/go makeOptions.
+  //
+  // Suppliedness cannot be recovered after validate, hence here, and it must
+  // tell an ABSENT auth from a present null: containsKey rather than a null
+  // check on the value, which cannot distinguish them.
+  val authSuppressed = options.containsKey("auth") && null == options["auth"]
+
   var opts = Struct.clone(options) as MutableMap<String, Any?>
 
+  if (authSuppressed) {
+    opts.remove("auth")
+  }
+
   // Feature add-order. options.feature may be given as an ordered LIST of
   // { name, active, ...opts } entries (the list position IS the order in which
   // features are added), or as a { name: {opts} } map. Normalize a list to a
@@ -107,6 +123,11 @@ fun makeOptions(ctx: Context): MutableMap<String, Any?> {
   val validated = Struct.validate(merged, optspec, vopts)
   opts = validated as MutableMap<String, Any?>
 
+  // Restore the suppression the optspec default would otherwise erase.
+  if (authSuppressed) {
+    opts["auth"] = null
+  }
+
   // Restore system.fetch.
   if (sysFetch != null) {
     val sys = Helpers.toMapAny(opts["system"])

package/project/.sdk/tm/lean/src/SdkUtility.lean

@@ -260,8 +260,19 @@ def prepareAuth (ctx : Value) : SIO (Value × Option Value) := do
   | .map _ => do
     let headers ← gpMap specV "headers"
     let options ← gp ctx "options"
+    -- `auth: null` is the documented way to suppress auth outright: NO
+    -- authorization header, whatever the apikey says. Without this the
+    -- withheld credential goes on the wire.
+    --
+    -- The ports that run options through validate against an optspec carrying
+    -- an `auth` default can use absence as the signal (validate guarantees the
+    -- key is present otherwise). lean's makeOptions has no optspec, so `auth`
+    -- is ABSENT in the ordinary case and absence must stay the ordinary case.
+    -- getpropRaw is the only reader that tells a STORED null from an absent
+    -- key - gp collapses both to .noval - so the stored null alone suppresses.
+    let authRaw ← getpropRaw options "auth"
     let apikey ← gpS options "apikey"
-    if apikey == "" then do
+    if authRaw == .null || apikey == "" then do
       dp headers "authorization"
       pure (specV, none)
     else do

package/project/.sdk/tm/lua/test/runner.lua

@@ -146,6 +146,46 @@ function runner.is_control_skipped(kind, name, mode)
 end
 
 
+-- Extra SDK options every LIVE client is constructed with, read from
+-- sdk-test-control.json `test.client.options`.
+--
+-- The generated live client knows two things: the base URL (from the spec)
+-- and the credential (from the environment). Everything else about how a
+-- particular API wants to be talked to - which features to switch on, and
+-- with what settings - is a property of THAT API, known to the project and
+-- to nothing in the toolchain.
+--
+-- Merged UNDER the generated fields, so the suite's own base/apikey/server
+-- values win: this ADDS to the live client, it does not redirect it.
+--
+-- Reserved fields are stripped HERE rather than at each merge site: the
+-- generated table only names a field when the model calls for one, so a
+-- "base" in this block would face no competing value and would silently
+-- redirect the whole suite - credential included - to another host.
+local LIVE_RESERVED = {
+  base = true, prefix = true, suffix = true,
+  server = true, apikey = true, secret = true,
+}
+
+function runner.live_client_options()
+  local ctrl = runner.load_test_control()
+  local test = ctrl.test
+  if type(test) ~= "table" then return {} end
+  local client = test.client
+  if type(client) ~= "table" then return {} end
+  local opts = client.options
+  if type(opts) ~= "table" then return {} end
+
+  local out = {}
+  for k, v in pairs(opts) do
+    if not LIVE_RESERVED[k] then
+      out[k] = v
+    end
+  end
+  return out
+end
+
+
 -- Per-test live pacing delay (ms); default 500.
 function runner.live_delay_ms()
   local ctrl = runner.load_test_control()

package/project/.sdk/tm/ocaml/sdk_runtime.ml

@@ -968,7 +968,16 @@ let make_options_util (ctx : ctx) : value =
       | Some u -> List.iter (fun k -> setp u.u_custom k (getp custom_utils k)) (keysof custom_utils)
       | None -> ())
    | _ -> ());
+  (* `auth: null` is the documented way to suppress auth outright. validate()
+     treats a STORED null as "no value" (getprop returns the alt), so the
+     optspec `auth` default would fire and turn the suppression into "use the
+     default auth" - transmitting a credential the caller withheld. getprop_raw
+     is the only reader that tells a stored Null from an absent key. Withhold
+     the key across merge/validate, then restore the null below. *)
+  let auth_suppressed =
+    (match getprop_raw options "auth" with Null -> true | _ -> false) in
   let opts = match clone options with Map _ as m -> m | _ -> empty_map () in
+  let () = if auth_suppressed then ignore (delprop opts (Str "auth")) in
   (* Feature add-order. options.feature may be given as an ordered LIST of
      {name; active; ...opts} entries (list position = add order) or a
      {name => {opts}} map. Normalize a list to a map (so merge/validate/init
@@ -999,6 +1008,8 @@ let make_options_util (ctx : ctx) : value =
   let merged = merge (ja [empty_map (); cfgopts; opts]) in
   let validated = validate merged optspec in
   let opts = match validated with Map _ as m -> m | _ -> empty_map () in
+  (* Restore the suppression the optspec default would otherwise erase. *)
+  let () = if auth_suppressed then setp opts "auth" Null in
   (* Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
      Every placeholder must resolve to a non-empty value: from options.server
      (user), else the Config default. A placeholder that resolves to "" is a

package/project/.sdk/tm/ocaml/test/harness.ml

@@ -93,14 +93,24 @@ let make_client ?(server : server option) ?(mode = "test") ?(base = "http://api.
   rootctx.c_op <- new_operation (jo [("name", Str "root"); ("entity", Str "_")]);
   client.cl_rootctx <- Some rootctx;
   List.iter (fun (name, opts) ->
-      if has_feature name then begin
-        let ftr = Sdk_config.make_feature name in
+      (* `netsim` is a test-only network simulator implemented in
+         Sdk_features, not a model feature, so it never appears in the
+         generated config and has_feature rejects it. Construct it directly:
+         without this every netsim-driven test (retry backoff, timeout,
+         and the metrics/telemetry/audit error paths) silently runs against
+         an unsimulated transport and sees a plain 200. *)
+      let ftr =
+        if name = "netsim" then Some (Sdk_features.netsim_feature ())
+        else if has_feature name then Some (Sdk_config.make_feature name)
+        else None in
+      match ftr with
+      | None -> ()
+      | Some ftr ->
         let fopts = jo [("active", Bool true)] in
         (match opts with Map _ -> List.iter (fun k -> setp fopts k (getp opts k)) (keysof opts) | _ -> ());
         setp (getp client.cl_options "feature") name fopts;
         ftr.f_init rootctx fopts;
-        client.cl_features <- client.cl_features @ [ftr]
-      end) features;
+        client.cl_features <- client.cl_features @ [ftr]) features;
   feature_hook_util rootctx "PostConstruct";
   { h_base = base; h_headers = hheaders; h_client = client; h_utility = utility; h_rootctx = rootctx }
 

package/project/.sdk/tm/perl/t/runner.pm

@@ -129,6 +129,36 @@ sub is_control_skipped {
   return (0, undef);
 }
 
+# Extra SDK options every LIVE client is constructed with, read from
+# sdk-test-control.json `test.client.options`.
+#
+# The generated live client knows two things: the base URL (from the spec)
+# and the credential (from the environment). Everything else about how a
+# particular API wants to be talked to - which features to switch on, and
+# with what settings - is a property of THAT API, known to the project and
+# to nothing in the toolchain.
+#
+# Merged UNDER the generated fields, so the suite's own base/apikey/server
+# values win: this ADDS to the live client, it does not redirect it.
+#
+# Reserved fields are stripped HERE rather than at each merge site: the
+# generated hash only names a field when the model calls for one, so a
+# "base" in this block would face no competing value and would silently
+# redirect the whole suite - credential included - to another host.
+my %LIVE_RESERVED = map { $_ => 1 }
+  qw(base prefix suffix server apikey secret);
+
+sub live_client_options {
+  my $ctrl = load_test_control();
+  my $opts = ProjectNameHelpers::gpath($ctrl, 'test.client.options');
+  return {} unless Voxgig::Struct::ismap($opts);
+  my %out;
+  for my $k (keys %$opts) {
+    $out{$k} = $opts->{$k} unless $LIVE_RESERVED{$k};
+  }
+  return \%out;
+}
+
 # Per-test live pacing delay (ms); default 500.
 sub live_delay_ms {
   my $ctrl = load_test_control();

package/project/.sdk/tm/perl/utility/make_options.pm

@@ -69,7 +69,22 @@ $REGISTRY{make_options} = sub {
   # reads options.extend, but clone/validate dropped the instances.
   my $extend_raw = ProjectNameHelpers::gp($options, 'extend');
 
+  # `auth => undef` is the documented way to disable auth outright, and
+  # prepare_auth honours it before it ever reads the apikey. It cannot survive
+  # validate: depending on the struct port a stored null is either REPLACED by
+  # the optspec default - transmitting the credential the caller withheld - or
+  # REJECTED outright. Withhold the key for validate, then put the undef back.
+  # Same fix as ts/js/go make_options.
+  #
+  # Suppliedness cannot be recovered after validate, hence here, and it must
+  # tell an ABSENT auth from a present undef: exists rather than defined,
+  # which is false for both.
+  my $authsuppressed =
+    (ref($options) eq 'HASH' && exists $options->{auth} && !defined $options->{auth}) ? 1 : 0;
+
   my $opts = Voxgig::Struct::clone($options);
+
+  delete $opts->{auth} if $authsuppressed && ref($opts) eq 'HASH';
   $opts = {} unless Voxgig::Struct::ismap($opts);
   delete $opts->{extend};
 
@@ -143,6 +158,9 @@ $REGISTRY{make_options} = sub {
   my $validated = Voxgig::Struct::validate($merged, $optspec);
   $opts = Voxgig::Struct::ismap($validated) ? $validated : {};
 
+  # Restore the suppression the optspec default would otherwise erase.
+  $opts->{auth} = undef if $authsuppressed;
+
   if ($sys_fetch) {
     $opts->{system} = {} unless Voxgig::Struct::ismap($opts->{system});
     $opts->{system}{fetch} = $sys_fetch;

package/project/.sdk/tm/php/test/FeatureCorpusTest.php

@@ -91,7 +91,16 @@ class FeatureCorpusTest extends TestCase
      */
     private static function buildClient(array $kase)
     {
-        $opts = ['utility' => ['fetcher' => self::scriptedFetcher($kase['res'] ?? null)]];
+        // 'test' here is the OPTION, not the `test` FEATURE. It says "this
+        // client is not live", which is what makes a REQUIRED OpenAPI server
+        // variable resolve to a deterministic test-<name> rather than throw
+        // at construction (see makeOptions). It installs no transport, so the
+        // scripted fetcher still stands - the FEATURE is transport: 'base'
+        // and would shadow it.
+        $opts = [
+            'test' => ['active' => true],
+            'utility' => ['fetcher' => self::scriptedFetcher($kase['res'] ?? null)],
+        ];
         if (isset($kase['feature'])) {
             $opts['feature'] = $kase['feature'];
         }

package/project/.sdk/tm/php/test/Runner.php

@@ -138,6 +138,42 @@ class ProjectNameTestRunner
         return [false, null];
     }
 
+    /**
+     * Extra SDK options every LIVE client is constructed with, read from
+     * sdk-test-control.json `test.client.options`.
+     *
+     * The generated live client knows two things: the base URL (from the
+     * spec) and the credential (from the environment). Everything else
+     * about how a particular API wants to be talked to - which features to
+     * switch on, and with what settings - is a property of THAT API, known
+     * to the project and to nothing in the toolchain.
+     *
+     * Merged UNDER the generated fields, so the suite's own
+     * base/apikey/server values win: this ADDS to the live client, it does
+     * not redirect it.
+     *
+     * Reserved fields are stripped HERE rather than at each merge site: the
+     * generated array only names a field when the model calls for one, so a
+     * "base" in this block would face no competing value and would silently
+     * redirect the whole suite - credential included - to another host.
+     */
+    public static function live_client_options(): array
+    {
+        $ctrl = self::load_test_control();
+        $opts = $ctrl['test']['client']['options'] ?? null;
+        if (!is_array($opts)) {
+            return [];
+        }
+        $reserved = ['base', 'prefix', 'suffix', 'server', 'apikey', 'secret'];
+        $out = [];
+        foreach ($opts as $k => $v) {
+            if (!in_array($k, $reserved, true)) {
+                $out[$k] = $v;
+            }
+        }
+        return $out;
+    }
+
     /** Per-test live pacing delay (ms); default 500. */
     public static function live_delay_ms(): int
     {

package/project/.sdk/tm/php/utility/MakeOptions.php

@@ -94,12 +94,31 @@ class ProjectNameMakeOptions
             }
         }
 
+        // `auth: null` is the documented way to disable auth outright, and
+        // prepareAuth honours it before it ever reads the apikey. It cannot
+        // survive validate: depending on the struct port a stored null is
+        // either REPLACED by the optspec default - transmitting the
+        // credential the caller withheld - or REJECTED outright. Withhold the
+        // key for validate, then put the null back. Same fix as ts/js/go
+        // makeOptions.
+        //
+        // Suppliedness cannot be recovered after validate, hence here, and it
+        // must tell an ABSENT auth from a present null: array_key_exists
+        // rather than isset, which is false for both.
+        $authsuppressed = is_array($options)
+            && array_key_exists('auth', $options)
+            && null === $options['auth'];
+
         $opts = \Voxgig\Struct\Struct::clone($options);
         $opts = self::to_array_deep($opts);
         if (!is_array($opts)) {
             $opts = [];
         }
 
+        if ($authsuppressed) {
+            unset($opts['auth']);
+        }
+
         // Feature add-order. options['feature'] may be given as an ordered LIST
         // of ['name'=>..., 'active'=>..., ...] entries (the list position IS the
         // order in which features are added), or as a ['name'=>[opts]] map.
@@ -164,6 +183,11 @@ class ProjectNameMakeOptions
             $opts = [];
         }
 
+        // Restore the suppression the optspec default would otherwise erase.
+        if ($authsuppressed) {
+            $opts['auth'] = null;
+        }
+
         // Reattach the station binding handle held aside above (the feature
         // optspec is `$OPEN`, so the extra keys are legal; they were only
         // kept out of the clone/validate round-trip).

package/project/.sdk/tm/py/pkg/utility/make_options.py

@@ -65,10 +65,26 @@ def make_options_util(ctx):
     if isinstance(options, dict) and options.get("extend") is not None:
         options = {k: v for k, v in options.items() if k != "extend"}
 
+    # `auth: None` is the documented way to disable auth outright, and
+    # prepare_auth honours it before it ever reads the apikey. It cannot
+    # survive validate: depending on the struct port a stored null is either
+    # REPLACED by the optspec default — transmitting the credential the
+    # caller withheld — or REJECTED outright. Withhold the key for validate,
+    # then put the null back. Same fix as ts/js/go make_options.
+    #
+    # Suppliedness cannot be recovered after validate, hence here, and it
+    # must tell an ABSENT auth from a present None: only the latter is a
+    # suppression.
+    authsuppressed = (
+        isinstance(options, dict) and "auth" in options and options["auth"] is None)
+
     opts = vs.clone(options)
     if not isinstance(opts, dict):
         opts = {}
 
+    if authsuppressed:
+        opts.pop("auth", None)
+
     # Feature add-order. options["feature"] may be given as an ordered LIST of
     # {name, active, ...opts} entries (the list position IS the order in which
     # features are added), or as a {name: {opts}} map. Normalize a list to a
@@ -162,6 +178,10 @@ def make_options_util(ctx):
         validated = {}
     opts = validated
 
+    # Restore the suppression the optspec default would otherwise erase.
+    if authsuppressed:
+        opts["auth"] = None
+
     # Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
     # Every placeholder must resolve to a non-empty value: from
     # options["server"] (user), else the config default. A placeholder that

package/project/.sdk/tm/py/test/runner.py

@@ -101,6 +101,34 @@ class ProjectNameTestRunner:
                     return True, item.get("reason")
         return False, None
 
+    @staticmethod
+    def live_client_options():
+        """Extra SDK options every LIVE client is constructed with, from
+        sdk-test-control.json `test.client.options`.
+
+        The generated live client knows two things: the base URL (from the
+        spec) and the credential (from the environment). Everything else
+        about how a particular API wants to be talked to - which features to
+        switch on, and with what settings - is a property of THAT API, known
+        to the project and to nothing in the toolchain.
+
+        Merged UNDER the generated fields, so the suite's own
+        base/apikey/server values win: this ADDS to the live client, it does
+        not redirect it.
+
+        Reserved fields are stripped HERE rather than at each merge site:
+        the generated dict only names a field when the model calls for one,
+        so a "base" in this block would face no competing value and would
+        silently redirect the whole suite - credential included - to another
+        host.
+        """
+        ctrl = ProjectNameTestRunner.load_test_control()
+        opts = ctrl.get("test", {}).get("client", {}).get("options")
+        if not isinstance(opts, dict):
+            return {}
+        reserved = ("base", "prefix", "suffix", "server", "apikey", "secret")
+        return {k: v for k, v in opts.items() if k not in reserved}
+
     @staticmethod
     def live_delay_ms():
         """Per-test live pacing delay (ms); default 500."""
@@ -161,5 +189,9 @@ def load_test_control():
     return ProjectNameTestRunner.load_test_control()
 
 
+def live_client_options():
+    return ProjectNameTestRunner.live_client_options()
+
+
 def live_delay_ms():
     return ProjectNameTestRunner.live_delay_ms()

package/project/.sdk/tm/py/test/test_feature_corpus.py

@@ -95,7 +95,16 @@ def _client(kase):
     transport: 'base' and REPLACES the transport, so a client in test mode
     would shadow the script.
     """
-    opts = {"utility": {"fetcher": _scripted_fetcher(kase.get("res"))}}
+    # "test" here is the OPTION, not the `test` FEATURE. It says "this
+    # client is not live", which is what makes a REQUIRED OpenAPI server
+    # variable resolve to a deterministic test-<name> rather than raise at
+    # construction (see make_options). It installs no transport, so the
+    # scripted fetcher still stands - the FEATURE is transport: 'base' and
+    # would shadow it, which is why this cannot just turn the feature on.
+    opts = {
+        "test": {"active": True},
+        "utility": {"fetcher": _scripted_fetcher(kase.get("res"))},
+    }
     if kase.get("feature") is not None:
         opts["feature"] = kase["feature"]
     return ProjectNameSDK(opts)

package/project/.sdk/tm/rb/test/feature_corpus_test.rb

@@ -71,7 +71,15 @@ class FeatureCorpusTest < Minitest::Test
   # transport: 'base' and REPLACES the transport, so a client in test mode
   # would shadow the script.
   def build_client(kase)
-    opts = { "utility" => { "fetcher" => scripted_fetcher(kase["res"]) } }
+    # "test" here is the OPTION, not the `test` FEATURE. It says "this
+    # client is not live", which is what makes a REQUIRED OpenAPI server
+    # variable resolve to a deterministic test-<name> rather than raise at
+    # construction (see make_options). It installs no transport, so the
+    # scripted fetcher still stands.
+    opts = {
+      "test" => { "active" => true },
+      "utility" => { "fetcher" => scripted_fetcher(kase["res"]) },
+    }
     opts["feature"] = kase["feature"] unless kase["feature"].nil?
     ProjectNameSDK.new(opts)
   end

package/project/.sdk/tm/rb/test/runner.rb

@@ -101,6 +101,31 @@ module ProjectNameTestRunner
     [false, nil]
   end
 
+  # Extra SDK options every LIVE client is constructed with, read from
+  # sdk-test-control.json `test.client.options`.
+  #
+  # The generated live client knows two things: the base URL (from the spec)
+  # and the credential (from the environment). Everything else about how a
+  # particular API wants to be talked to - which features to switch on, and
+  # with what settings - is a property of THAT API, known to the project and
+  # to nothing in the toolchain.
+  #
+  # Merged UNDER the generated fields, so the suite's own base/apikey/server
+  # values win: this ADDS to the live client, it does not redirect it.
+  #
+  # Reserved fields are stripped HERE rather than at each merge site: the
+  # generated hash only names a field when the model calls for one, so a
+  # "base" in this block would face no competing value and would silently
+  # redirect the whole suite - credential included - to another host.
+  LIVE_RESERVED = %w[base prefix suffix server apikey secret].freeze
+
+  def self.live_client_options
+    ctrl = load_test_control
+    opts = ctrl.dig('test', 'client', 'options')
+    return {} unless opts.is_a?(Hash)
+    opts.reject { |k, _v| LIVE_RESERVED.include?(k) }
+  end
+
   # Per-test live pacing delay (ms); default 500.
   def self.live_delay_ms
     ctrl = load_test_control