@voxgig/sdkgen 4.6.0 → 4.7.0

package/project/.sdk/src/cmp/scala/Main_scala.ts

@@ -5,6 +5,7 @@ import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
   targetFeatures,
+  TEST_CONTROL_EXCLUDE
 } from '@voxgig/sdkgen'
 
 
@@ -51,7 +52,7 @@ const Main = cmp(async function Main(props: any) {
   // ProjectName carries the SDK name into vendored template strings.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//],
+    exclude: [/src\//, TEST_CONTROL_EXCLUDE],
     replace: {
       ...props.ctx$.stdrep,
       ProjectName: model.const.Name,

package/project/.sdk/src/cmp/scala/Test_scala.ts

@@ -9,7 +9,8 @@ import type {
   ModelEntity
 } from '@voxgig/apidef'
 
-import { cmp, each, Folder, File, Content, entityCollection } from '@voxgig/sdkgen'
+import { cmp, each, Folder, File, Content, entityCollection,
+  TestControl } from '@voxgig/sdkgen'
 
 
 import { TestEntity } from './TestEntity_scala'
@@ -31,6 +32,9 @@ const Test = cmp(function Test(props: any) {
   // template, and are driven by the generated SdkEntityTestMain aggregator.
   Folder({ name: 'sdktest' }, () => {
 
+    // Write-once: a project's edited control file survives regeneration.
+    TestControl({ target, dir: 'sdktest' })
+
     const entities: { Name: string; entity: boolean; direct: boolean }[] = []
 
     const entity = each(entityCollection(model))

package/project/.sdk/src/cmp/ts/Config_ts.ts

@@ -99,10 +99,13 @@ const Config = cmp(async function Config(props: any) {
 
         replace: {
 
-          '// #ImportFeatures': () => each(feature, (f: any) => {
-            Line(`import { ${nom(f, 'Name')}Feature } from ` +
-              `'./feature/${f.name}/${nom(f, 'Name')}Feature'`)
-          }),
+          '// #ImportFeatures': () => {
+            each(feature, (f: any) => {
+              Line(`import { ${nom(f, 'Name')}Feature } from ` +
+                `'./feature/${f.name}/${nom(f, 'Name')}Feature'`)
+            })
+            pluginImports(feature)
+          },
 
           '// #FeatureClasses': () => each(feature, (f: any) => {
             Line(` ${f.name}: ${nom(f, 'Name')}Feature,`)
@@ -130,10 +133,13 @@ const Config = cmp(async function Config(props: any) {
 
         "'HEADERS'": indent(JSON.stringify(headers, null, 2), 4).trim(),
 
-        '// #ImportFeatures': () => each(feature, (f: any) => {
-          Line(`import { ${nom(f, 'Name')}Feature } from ` +
-            `'./feature/${f.name}/${nom(f, 'Name')}Feature'`)
-        }),
+        '// #ImportFeatures': () => {
+          each(feature, (f: any) => {
+            Line(`import { ${nom(f, 'Name')}Feature } from ` +
+              `'./feature/${f.name}/${nom(f, 'Name')}Feature'`)
+          })
+          pluginImports(feature)
+        },
 
         // Values from configDefinition's def, not re-derived here, so the
         // literal rep and the data rep cannot disagree on identity.
@@ -177,6 +183,42 @@ const Config = cmp(async function Config(props: any) {
 })
 
 
+
+// PLUGIN REGISTRATION IMPORTS.
+//
+// A sekreto provider module registers itself when it is imported, and
+// nothing else imports it: the core surface deliberately does not reach a
+// platform-dependent provider, and the full-set barrel — the file whose
+// job was to reach all of them — is not vendored into an SDK at all.
+//
+// So without these lines an SDK generates `provider/dotenv.ts`, never
+// imports it, and throws `unknown provider kind: dotenv` the first time a
+// chain names it. Emitted here because Config already imports every active
+// feature from the model, and this is the same list one level down.
+//
+// Import for SIDE EFFECT only — `import '...'`, no bindings. The module's
+// top-level `register()` call is the whole point.
+function pluginImports(feature: any) {
+  each(feature, (f: any) => {
+    each(f.plugin, (plugin: any) => {
+      // Filter on `active` HERE rather than trusting the feature object to
+      // arrive filtered. Whether a model path was read with `only_active`
+      // varies by call site, and getting it wrong in this direction emits
+      // an import for a module the trim just deleted — an SDK that does
+      // not compile, rather than one that merely carries too much.
+      if (false === plugin.active || null == plugin.active) return
+
+      for (const one of (plugin.path || [])) {
+        const path = String(one)
+        // Only a provider MODULE registers a kind; a plugin may own other
+        // files (Sigv4.ts is signing support, not a provider).
+        if (!/\/provider\/[^/]+\.ts$/.test(path)) continue
+        Line(`import '${'./' + path.replace(/^src\//, '').replace(/\.ts$/, '')}'`)
+      }
+    })
+  })
+}
+
 export {
   Config
 }

package/project/.sdk/src/cmp/ts/Main_ts.ts

@@ -4,8 +4,10 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
-  entityClassName, entityCollection, srcFeatureExcludes, stationLibrary,
+  entityClassName, entityCollection, srcFeatureExcludes, pluginExcludes,
+  stationLibrary,
   targetFeatures,
+  TEST_CONTROL_EXCLUDE
 } from '@voxgig/sdkgen'
 
 
@@ -53,7 +55,13 @@ const Main = cmp(async function Main(props: any) {
     from: 'tm/' + target.name,
     // Root copies src/feature/<name>/ per ACTIVE feature; keep this blanket
     // copy from restoring one that was switched off after `target add`.
-    exclude: srcFeatureExcludes(model),
+    // A feature's inactive plugins go too - same rule, one level
+    // deeper. See helpers/featureSource.pluginExcludes.
+    exclude: [
+      ...srcFeatureExcludes(model),
+      ...pluginExcludes(model),
+      TEST_CONTROL_EXCLUDE,
+    ],
     replace: {
       ...props.ctx$.stdrep,
     }

package/project/.sdk/src/cmp/ts/TestDirect_ts.ts

@@ -21,7 +21,8 @@ import {
   serverVariables,
   isHttpBasicAuth,
   jsProp,
-  jsOptProp, envName, envToken, liveStrict
+  jsOptProp, envName, envToken, liveStrict,
+  jsKey
 } from '@voxgig/sdkgen'
 
 
@@ -49,7 +50,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const authActive = isAuthActive(model)
   const authBasic = authActive && isHttpBasicAuth(model)
   const apikeyEnvEntry = authActive
-    ? `\n    '${PROJECTNAME}_APIKEY': '',${authBasic ? `\n    '${PROJECTNAME}_SECRET': 'NONE',` : ''}`
+    ? `\n    '${PROJECTNAME}_APIKEY': '',${authBasic ? `\n    '${PROJECTNAME}_SECRET': '',` : ''}`
     : ''
   const apikeyLiveField = authActive
     ? `
@@ -61,13 +62,19 @@ const TestDirect = cmp(function TestDirect(props: any) {
   // impossible to construct without values: makeOptions raises rather than
   // request a URL with a literal `{account_id}` in it. Taken from the
   // environment, the same way the apikey is.
+  //
+  // Keys are quoted and the env read is bracketed via jsKey/jsProp: a server
+  // variable name is spec-derived and need not be a JS identifier — the URL
+  // grammar admits a leading digit ({2fa}), and a declared-but-unreferenced
+  // variable ({edge-zone}) is not constrained at all. Bare `name:` and
+  // `env.PROJ_SERVER_EDGE-ZONE` are both syntax errors.
   const svars = serverVariables(model)
   const serverEnvEntry = svars
     .map((v: any) => `\n    '${serverVarEnv(PROJECTNAME, v.name)}': ${JSON.stringify(v.dflt)},`).join('')
   const serverLiveField = 0 === svars.length ? '' : `
       server: {${svars
       .map((v: any) => `
-        ${v.name}: env.${serverVarEnv(PROJECTNAME, v.name)},`).join('')}
+        ${jsKey(v.name)}: ${jsProp('env', serverVarEnv(PROJECTNAME, v.name))},`).join('')}
       },`
 
   const opnames = Object.keys(entity.op || {})

package/project/.sdk/src/cmp/ts/TestEntity_ts.ts

@@ -33,7 +33,9 @@ import {
   serverVarEnv,
   serverVariables,
   isHttpBasicAuth,
-  entityDataIdField, envName, envToken
+  entityDataIdField, envName, envToken,
+  jsKey,
+  jsProp
 } from '@voxgig/sdkgen'
 
 
@@ -69,7 +71,7 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const authActive = isAuthActive(model)
   const authBasic = authActive && isHttpBasicAuth(model)
   const apikeyEnvEntry = authActive
-    ? `\n    '${PROJENVNAME}_APIKEY': '',${authBasic ? `\n    '${PROJENVNAME}_SECRET': 'NONE',` : ''}`
+    ? `\n    '${PROJENVNAME}_APIKEY': '',${authBasic ? `\n    '${PROJENVNAME}_SECRET': '',` : ''}`
     : ''
   const apikeyLiveField = authActive
     ? `
@@ -81,13 +83,19 @@ const TestEntity = cmp(function TestEntity(props: any) {
   // impossible to construct without values: makeOptions raises rather than
   // request a URL with a literal `{account_id}` in it. So the live suite
   // takes them from the environment the same way it takes the apikey.
+  //
+  // Keys are quoted and the env read is bracketed via jsKey/jsProp: a server
+  // variable name is spec-derived and need not be a JS identifier — the URL
+  // grammar admits a leading digit ({2fa}), and a declared-but-unreferenced
+  // variable ({edge-zone}) is not constrained at all. Bare `name:` and
+  // `env.PROJ_SERVER_EDGE-ZONE` are both syntax errors.
   const svars = serverVariables(model)
   const serverEnvEntry = svars
     .map((v: any) => `\n    '${serverVarEnv(PROJENVNAME, v.name)}': ${JSON.stringify(v.dflt)},`).join('')
   const serverLiveField = 0 === svars.length ? '' : `
         server: {${svars
       .map((v: any) => `
-          ${v.name}: env.${serverVarEnv(PROJENVNAME, v.name)},`).join('')}
+          ${jsKey(v.name)}: ${jsProp('env', serverVarEnv(PROJENVNAME, v.name))},`).join('')}
         },`
 
   // TODO: should be a utility function

package/project/.sdk/src/cmp/ts/Test_ts.ts

@@ -3,7 +3,8 @@ import type {
   ModelEntity
 } from '@voxgig/apidef'
 
-import { cmp, each, Folder, entityCollection } from '@voxgig/sdkgen'
+import { cmp, each, Folder, entityCollection,
+  TestControl } from '@voxgig/sdkgen'
 
 
 // import { Quick } from './Quick_ts'
@@ -19,6 +20,9 @@ const Test = cmp(function Test(props: any) {
   const { target } = props
 
   Folder({ name: 'test' }, () => {
+
+    // Write-once: a project's edited control file survives regeneration.
+    TestControl({ target, dir: 'test' })
     // Quick({ target })
     // TestMain({ target })
 

package/project/.sdk/tm/csharp/test/Runner.cs

@@ -153,6 +153,51 @@ public static class TestRunner
         return _testControl;
     }
 
+    // LiveClientOptions returns the 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 dictionary 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.
+    private static readonly string[] LiveReserved =
+        { "base", "prefix", "suffix", "server", "apikey", "secret" };
+
+    public static Dictionary<string, object?> LiveClientOptions()
+    {
+        var ctrl = LoadTestControl();
+        if (!ctrl.TryGetValue("test", out var testRaw) ||
+            testRaw is not Dictionary<string, object?> test ||
+            !test.TryGetValue("client", out var clientRaw) ||
+            clientRaw is not Dictionary<string, object?> client ||
+            !client.TryGetValue("options", out var optsRaw) ||
+            optsRaw is not Dictionary<string, object?> opts)
+        {
+            return new Dictionary<string, object?>();
+        }
+
+        var out_ = new Dictionary<string, object?>();
+        foreach (var kv in opts)
+        {
+            if (Array.IndexOf(LiveReserved, kv.Key) < 0)
+            {
+                out_[kv.Key] = kv.Value;
+            }
+        }
+        return out_;
+    }
+
     // IsControlSkipped checks sdk-test-control.json for a skip entry.
     // Returns (skip, reason).
     public static (bool, string) IsControlSkipped(string kind, string name, string mode)

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

@@ -143,6 +143,45 @@ bool skipIfMissingIds(T t, Map setup, List<String> requiredKeys) {
 
 // Per-test live pacing delay (ms). Read from sdk-test-control.json
 // `test.live.delayMs`; defaults to 500ms if absent or invalid.
+// 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 map 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.
+const List<String> liveReserved = [
+  'base', 'prefix', 'suffix', 'server', 'apikey', 'secret'
+];
+
+Map<String, dynamic> liveClientOptions() {
+  final ctrl = loadTestControl();
+  final t = ctrl['test'];
+  if (t is! Map) return <String, dynamic>{};
+  final c = t['client'];
+  if (c is! Map) return <String, dynamic>{};
+  final opts = c['options'];
+  if (opts is! Map) return <String, dynamic>{};
+
+  final out = <String, dynamic>{};
+  opts.forEach((k, v) {
+    if (!liveReserved.contains(k)) {
+      out['$k'] = v;
+    }
+  });
+  return out;
+}
+
+
 int liveDelayMs() {
   final ctrl = loadTestControl();
   final t = ctrl['test'];

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/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/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/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/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