@voxgig/sdkgen 4.5.3 → 4.6.0

package/model/sdkgen.aon

@@ -172,6 +172,27 @@ main: kit: target: &: {
   ext: string
   comment: line: string
 
+  # APPLICABILITY (docs/design/feature-tags.md). What this target can offer
+  # a feature; a feature applies here when its `needs` is a subset of this.
+  # Empty is the default, so a target says nothing until it has a reason to.
+  #
+  # THE VOCABULARY IS CLOSED — extended by editing this comment and the
+  # schema, never by a package inventing a string. Two authors spelling the
+  # same capability differently is the whole failure mode a free-form tag
+  # would reintroduce.
+  #
+  #   sekreto   a vendored sekreto port lives in this target's feature
+  #             container, so a feature can resolve secrets through it
+  #
+  # Tags named in the design note but not yet load-bearing
+  # (`per-feature-file`, `deps`, `transport-wrap`, `hooks`, `delegates`)
+  # are deliberately absent until a feature actually gates on one: a tag
+  # whose answer is currently "everyone" buys nothing and has to be kept
+  # true across 27 targets.
+  #
+  # A map keyed by tag, matching `needs` — see the note there.
+  provides: &: boolean
+
   base:     *'' | string
   origname: *'' | string
   package:  *'' | string
@@ -420,6 +441,24 @@ main: kit: feature: &: {
   # TODO: version '0.0.1' | semver # where semver is a string format type as per semver.org
   version: *'0.0.1' | string
 
+  # APPLICABILITY (docs/design/feature-tags.md). What this feature requires
+  # of a target; it applies where `needs` is a subset of the target's
+  # `provides`. Empty means "applies anywhere", so every feature that
+  # predates the gate is unaffected — the gate is additive by construction.
+  #
+  # A tag, not a target list: a list has to be edited for targets the
+  # feature's author has never heard of, so a published package would
+  # starve every target added after its release.
+  #
+  # The vocabulary is closed and lives in `main: kit: target: &: provides`.
+  #
+  # A MAP keyed by tag, not a list, for the reason `contributor` is a map:
+  # aontu unifies maps by key, so a package can add one tag without
+  # restating the others. A list here also hangs the unifier outright on a
+  # real project's model (a defaulted list disjunction under this spread),
+  # which is what settled the shape.
+  needs: &: boolean
+
   # Transport role (station design §8.4): how the feature relates to the
   # transport slot. 'base' REPLACES ctx.utility.fetcher outright (only the
   # `test` feature); 'wrap' wraps it in init() (netsim, retry, cache,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "4.5.3",
+  "version": "4.6.0",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "engines": {

package/project/.sdk/model/feature/feature-index.aon

@@ -3,6 +3,7 @@
 # Core
 @"test.aon"
 @"log.aon"
+@"secrets.aon"
 
 # Enterprise capabilities
 @"retry.aon"

package/project/.sdk/model/feature/secrets.aon

@@ -0,0 +1,118 @@
+
+main: kit: feature: secrets: {
+
+  name: key()
+  title: "Secret access: resolve the API credential through a provider chain, and exchange a refresh token for short-lived access tokens"
+  version: '0.1.0'
+  base: 'BASE'
+
+  # `active` is deliberately NOT set here. The base schema defaults it
+  # (`active: *false | boolean`), and in aontu a concrete value does not
+  # yield to another concrete value — it CONFLICTS. Restating `active:
+  # false` here would make a project's `main: kit: feature: secrets:
+  # active: true` fail to unify, which is the same defect the publication
+  # keys carry a warning about in model/target/ts.aon.
+  #
+  # So the feature is OFF until a project turns it on, in its own overlay
+  # (model/project.aon), which `feature add` never overwrites.
+
+  # Applicability (docs/design/feature-tags.md). The feature is a thin
+  # layer over a VENDORED sekreto port, so it only applies to a target
+  # whose feature container carries one. Without this tag the feature
+  # would fan out to every target, and each one that generated would
+  # carry an import for a class it has no source for.
+  needs: { sekreto: true }
+
+  # Transport role (station design §8.4).
+  #
+  # 'wrap', because the access-token exchange below has to SEE the response:
+  # a spent token is discovered by the API answering 401, and the only place
+  # to notice that and try again is around the transport. It wraps only when
+  # `exchange.active` — with the exchange off this feature never touches the
+  # transport, exactly as when its role was 'none' — but the role is a
+  # DECLARATION of what the feature may do, not a report of what one
+  # configuration does, so it is declared at its widest.
+  transport: 'wrap'
+
+  config: {
+    options: {
+      active: false
+
+      # The sekreto provider chain, in first-hit order. Each entry is a
+      # sekreto ProviderSpec ({ kind, name, ... }) or a provider object.
+      # An explicit `apikey` option, when set, is placed AHEAD of these as
+      # a `memory` store named 'options', so an explicit credential still
+      # wins — by sekreto's own first-hit rule, not by special-casing.
+      providers: []
+
+      # The secret to resolve, for an API whose credential is not
+      # apikey-shaped. The resolved value is written to options.apikey
+      # regardless, because that is where prepareAuth looks.
+      name: 'apikey'
+
+      # sekreto caches resolved values by default. Off means every
+      # resolve() asks the chain again; redaction still tracks values.
+      cache: true
+
+      # ACCESS-TOKEN EXCHANGE (the OAuth2 refresh grant, in miniature).
+      #
+      # Some APIs do not accept a long-lived credential at all: the secret the
+      # chain above resolves is a REFRESH token, which buys a short-lived ACCESS
+      # token from a token endpoint, and that access token is what every request
+      # carries. The access token then expires, and the client is expected to buy
+      # another without human help.
+      #
+      # Off by default, and inert when off: with `exchange.active: false` this
+      # feature behaves exactly as it always did — resolve one secret, write it to
+      # options.apikey. That is what keeps the change additive for every SDK
+      # already using it.
+      #
+      # With it on, set `name` to the refresh secret (`name: 'refresh_token'`),
+      # because `name` is what the chain is asked for.
+      exchange: {
+        active: false
+
+        # The token endpoint, RELATIVE to options.base — the base already
+        # carries whatever account or tenant segment the server URL declares,
+        # so a relative path follows it without being told about it.
+        path: 'auth/token'
+        method: 'POST'
+
+        # The JSON field the refresh credential is SENT in, and the field the
+        # access token comes back in. Named rather than assumed: `access_token`
+        # and `refresh_token` are the OAuth2 spelling, and plenty of APIs use
+        # their own.
+        request: 'refresh_token'
+        response: 'access_token'
+
+        # An explicit refresh token, given in code. It becomes the FIRST
+        # provider in the chain, so it wins by sekreto's own first-hit rule —
+        # the same seat `options.apikey` takes when no exchange is configured.
+        # `options.apikey` cannot serve here: with an exchange configured it
+        # means "an access token I already hold", which is the opposite kind
+        # of credential.
+        refresh: ''
+
+        # Response statuses that mean "your access token is spent, buy
+        # another". 401 is the answer every API in this shape gives; 403 is
+        # listed by some, so it is configurable rather than assumed.
+        statuses: [401]
+
+        # How many times ONE request may buy a token and try again. One is
+        # right: a second refusal on a token bought moments ago is a real
+        # failure — a revoked refresh token, the wrong account — and retrying
+        # it turns that into a spin instead of an error.
+        retries: 1
+      }
+    }
+  }
+
+  # Resolution is ASYNC (a provider may do IO, and the exchange makes an
+  # HTTP request) but prepareAuth is sync.
+  # Entity ops await featureHook('PreSpec') before makeSpec, so this is
+  # the one seam where the lookup can happen and still land in time.
+  # Concurrent operations share the single in-flight promise.
+  hook: {
+    PreSpec: { active: true, await: true }
+  }
+}

package/project/.sdk/model/target/ts.aon

@@ -7,13 +7,20 @@ main: kit: target: ts: {
   module: name: '$$name$$'
   base: 'BASE'
 
+  # Applicability (docs/design/feature-tags.md). A vendored sekreto port
+  # lives in this target's feature container, so a feature that resolves
+  # secrets through sekreto can apply here.
+  provides: { sekreto: true }
+
   deps: &: {
     # TODO: fix aontu disjunctions!
     kind: *'prod' | string # 'peer' |'dev'
   }
   
   deps: {
-    'dotenv': { active: true, version: '^17.4.2', kind: dev }
+    # dotenv was dropped when the generated entity tests moved to
+    # `loadEnvLocal` (tm/ts/test/utility.ts) — the SDK's last non-tooling
+    # dependency of any kind.
     'typescript': { active: true, version: '^5.9.3', kind: dev }
     '@types/node': { active: true, version: '^25.6.0', kind: dev }
   }

package/project/.sdk/src/cmp/c/Config_c.ts

@@ -9,6 +9,7 @@ import {
   isAuthActive,
   isConfigData,
   resolveAuthPrefix,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -36,7 +37,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/cpp/Config_cpp.ts

@@ -5,6 +5,7 @@ import {
   cmp,
   configDefinition,
   each,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -30,7 +31,10 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // The embedded config, built by the shared helper so this target's shapes
   // and identity fields stay in step with the ts reference by construction.

package/project/.sdk/src/cmp/csharp/Config_csharp.ts

@@ -7,6 +7,7 @@ import {
   configReprSetting,
   each,
   isConfigData,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -33,7 +34,10 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // The same config as an OBJECT, built by the shared helper so this target's
   // literal and the data that replaces it above the threshold are the same

package/project/.sdk/src/cmp/dart/Config_dart.ts

@@ -13,6 +13,7 @@ import {
   isConfigData,
   isAuthActive,
   resolveAuthPrefix,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -38,7 +39,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/dart/fragment/')
 

package/project/.sdk/src/cmp/elixir/Config_elixir.ts

@@ -10,6 +10,7 @@ import {
   isAuthActive,
   isConfigData,
   resolveAuthPrefix,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -35,7 +36,10 @@ const Config = cmp(async function Config(props: any) {
   const Name = model.const.Name
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/elixir/Main_elixir.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each,
   File, Folder, Content, Copy, Fragment,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -38,7 +39,10 @@ const Main = cmp(async function Main(props: any) {
 
   const Name = model.const.Name
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/elixir/fragment/')
 

package/project/.sdk/src/cmp/go/Config_go.ts

@@ -16,6 +16,7 @@ import {
   isConfigData,
   resolveAuthPrefix,
   serverVariables,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -40,7 +41,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/go/Main_go.ts

@@ -4,7 +4,8 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
-  entityClassName, entityCollection, goModule, goPackageIdent
+  entityClassName, entityCollection, goModule, goPackageIdent,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -33,7 +34,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // Go module path == the repo path on GitHub (org from model.origin),
   // e.g. github.com/voxgig-sdk/<slug>-sdk. Used in go.mod and every import.

package/project/.sdk/src/cmp/go/ReadmeQuick_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps, goModule } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps, goModule , serverVariables} from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -25,9 +25,22 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
   const authActive = isAuthActive(model)
+  
+  // Server variables (a templated server URL) are REQUIRED at construction
+  // - the SDK refuses rather than request a URL with a literal
+  // {account_id} in it - so a quickstart that omits them is a quickstart
+  // that fails on its first line.
+  const svars = serverVariables(model)
+  const goServerField = 0 === svars.length ? '' :
+    `\n    "server": map[string]any{` +
+    svars.map((v: any) => `\n        "${v.name}": "<${v.name}>",`).join('') +
+    `\n    },`
+
   const ctor = authActive
-    ? `sdk.New${model.const.Name}SDK(map[string]any{\n        "apikey": os.Getenv("${envName(model)}_APIKEY"),\n    })`
-    : `sdk.New()`
+    ? `sdk.New${model.const.Name}SDK(map[string]any{\n        "apikey": os.Getenv("${envName(model)}_APIKEY"),${goServerField}\n    })`
+    : ('' === goServerField
+      ? `sdk.New()`
+      : `sdk.New${model.const.Name}SDK(map[string]any{${goServerField}\n    })`)
 
   // Build the body of main() from the operations the example entity
   // supports. Each op names a fresh value var, so `:=` always declares a

package/project/.sdk/src/cmp/go/ReadmeTopQuick_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, entityOps, opRequestShape, goModule } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityOps, opRequestShape, goModule , serverVariables} from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -20,9 +20,22 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
   const authActive = isAuthActive(model)
+  
+  // Server variables (a templated server URL) are REQUIRED at construction
+  // - the SDK refuses rather than request a URL with a literal
+  // {account_id} in it - so a quickstart that omits them is a quickstart
+  // that fails on its first line.
+  const svars = serverVariables(model)
+  const goServerField = 0 === svars.length ? '' :
+    `\n    "server": map[string]any{` +
+    svars.map((v: any) => `\n        "${v.name}": "<${v.name}>",`).join('') +
+    `\n    },`
+
   const ctor = authActive
-    ? `sdk.New${model.const.Name}SDK(map[string]any{\n    "apikey": os.Getenv("${envName(model)}_APIKEY"),\n})`
-    : `sdk.New()`
+    ? `sdk.New${model.const.Name}SDK(map[string]any{\n    "apikey": os.Getenv("${envName(model)}_APIKEY"),${goServerField}\n})`
+    : ('' === goServerField
+      ? `sdk.New()`
+      : `sdk.New${model.const.Name}SDK(map[string]any{${goServerField}\n})`)
 
   Content(`\`\`\`go
 import sdk "${gomodule}"

package/project/.sdk/src/cmp/go/TestDirect_go.ts

@@ -11,7 +11,9 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive, envName, envToken, liveStrict
+  isAuthActive,
+  serverVarEnv,
+  serverVariables, envName, envToken, liveStrict
 } from '@voxgig/sdkgen'
 
 
@@ -73,12 +75,26 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
-    ? `\n\t\t"${PROJECTNAME}_APIKEY":       "NONE",`
+    ? `\n\t\t"${PROJECTNAME}_APIKEY":       "",`
     : ''
   const apikeyLiveField = authActive
     ? `\n\t\t\t"apikey": env["${PROJECTNAME}_APIKEY"],`
     : ''
 
+  // A templated server URL (OpenAPI server variables) makes a LIVE client
+  // impossible to construct without values: makeOptions refuses rather than
+  // request a URL with a literal `{account_id}` in it. Taken from the
+  // environment, the same way the apikey is.
+  const svars = serverVariables(model)
+  const serverEnvEntry = svars
+    .map((v: any) => `\n\t\t"${serverVarEnv(PROJECTNAME, v.name)}": ${JSON.stringify(v.dflt)},`).join('')
+  const serverLiveField = 0 === svars.length ? '' :
+    `\n\t\t"server": map[string]any{` +
+    svars.map((v: any) =>
+      `\n\t\t\t"${v.name}": env["${serverVarEnv(PROJECTNAME, v.name)}"],`).join('') +
+    `\n\t\t},`
+
+
   const opnames = Object.keys(entity.op || {})
   const hasLoad = opnames.includes('load')
   const hasList = opnames.includes('list')
@@ -559,13 +575,21 @@ func ${entity.name}DirectSetup(mockres any) *${entity.name}DirectSetupResult {
 
 	env := envOverride(map[string]any{
 		"${entidEnvVar}": map[string]any{},
-		"${PROJECTNAME}_TEST_LIVE":    "FALSE",${apikeyEnvEntry}
+		"${PROJECTNAME}_TEST_LIVE":    "FALSE",${apikeyEnvEntry}${serverEnvEntry}
 	})
 
 	live := env["${PROJECTNAME}_TEST_LIVE"] == "TRUE"
 
 	if live {
-		mergedOpts := map[string]any{${apikeyLiveField}
+		// sdk-test-control.json's test.client.options seeds the live
+		// client; the generated fields below overwrite anything they name.
+		mergedOpts := map[string]any{}
+		for k, v := range liveClientOptions() {
+			mergedOpts[k] = v
+		}
+		for k, v := range map[string]any{${apikeyLiveField}${serverLiveField}
+		} {
+			mergedOpts[k] = v
 		}
 		client := sdk.New${model.const.Name}SDK(mergedOpts)
 

package/project/.sdk/src/cmp/go/TestEntity_go.ts

@@ -24,6 +24,8 @@ import {
   buildIdNames,
   getMatchEntries,
   isAuthActive,
+  serverVarEnv,
+  serverVariables,
   entityDataIdField, envName, envToken
 } from '@voxgig/sdkgen'
 
@@ -71,12 +73,26 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
-    ? `\n\t\t"${PROJUPPER}_APIKEY":         "NONE",`
+    ? `\n\t\t"${PROJUPPER}_APIKEY":         "",`
     : ''
   const apikeyLiveField = authActive
     ? `\n\t\t\t\t"apikey": env["${PROJUPPER}_APIKEY"],`
     : ''
 
+
+  // A templated server URL (OpenAPI server variables) makes a LIVE client
+  // impossible to construct without values: makeOptions refuses rather than
+  // request a URL with a literal `{account_id}` in it. Taken from the
+  // environment, the same way the apikey is.
+  const svars = serverVariables(model)
+  const serverEnvEntry = svars
+    .map((v: any) => `\n\t\t"${serverVarEnv(PROJUPPER, v.name)}": ${JSON.stringify(v.dflt)},`).join('')
+  const serverLiveField = 0 === svars.length ? '' :
+    `\n\t\t\t\t"server": map[string]any{` +
+    svars.map((v: any) =>
+      `\n\t\t\t\t\t"${v.name}": env["${serverVarEnv(PROJUPPER, v.name)}"],`).join('') +
+    `\n\t\t\t\t},`
+
   const idnames = buildIdNames(entity, basicflow)
   const idnamesStr = idnames.map(n => `"${n}"`).join(', ')
 
@@ -205,7 +221,7 @@ ${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
       const preambleRef = entity.name + '_ref01'
       const preambleVar = goVar(preambleRef)
       Content(`		// Bootstrap entity data from existing test data (no create step in flow).
-		${preambleVar}DataRaw := vs.Items(core.ToMapAny(vs.GetPath("existing.${entity.name}", setup.data)))
+		${preambleVar}DataRaw := vs.Items(core.ToMapAny(vs.GetPath(setup.data, "existing.${entity.name}")))
 		var ${preambleVar}Data map[string]any
 		if len(${preambleVar}DataRaw) > 0 {
 			${preambleVar}Data = core.ToMapAny(${preambleVar}DataRaw[0][1])
@@ -265,9 +281,14 @@ ${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
 
 `)
 
-    // Generate idmap via vs.Transform
+    // Generate idmap via vs.Transform.
+    //
+    // The error return Transform gained in struct go 0.1.3 is discarded
+    // deliberately: this transforms the entity's own id names, which the
+    // generator produced, so an error would be a generator bug rather than
+    // anything the generated test can act on.
     Content('\t// Generate idmap via transform, matching TS pattern.\n')
-    Content('\tidmap := vs.Transform(\n')
+    Content('\tidmap, _ := vs.Transform(\n')
     Content('\t\t[]any{' + idnamesStr + '},\n')
     Content('\t\tmap[string]any{\n')
     Content('\t\t\t"`$PACK`": []any{"", map[string]any{\n')
@@ -287,7 +308,7 @@ ${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
 	env := envOverride(map[string]any{
 		"${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID": idmap,
 		"${PROJUPPER}_TEST_LIVE":      "FALSE",
-		"${PROJUPPER}_TEST_EXPLAIN":   "FALSE",${apikeyEnvEntry}
+		"${PROJUPPER}_TEST_EXPLAIN":   "FALSE",${apikeyEnvEntry}${serverEnvEntry}
 	})
 
 	idmapResolved := core.ToMapAny(env["${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID"])
@@ -307,10 +328,22 @@ ${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
 
     Content(`
 	if env["${PROJUPPER}_TEST_LIVE"] == "TRUE" {
+		// An empty map, not a nil one: Merge returns nil when its last entry
+		// is nil, and BasicSetup is normally called with no extras - so a
+		// bare nil silently discarded the apikey and server values below.
+		extraOpts := extra
+		if extraOpts == nil {
+			extraOpts = map[string]any{}
+		}
+
 		mergedOpts := vs.Merge([]any{
-			map[string]any{${apikeyLiveField}
+			// liveClientOptions() FIRST, so the generated fields below win:
+			// sdk-test-control.json's test.client.options adds to the live
+			// client, it does not redirect it.
+			liveClientOptions(),
+			map[string]any{${apikeyLiveField}${serverLiveField}
 			},
-			extra,
+			extraOpts,
 		})
 		client = sdk.New${model.const.Name}SDK(core.ToMapAny(mergedOpts))
 	}
@@ -361,11 +394,11 @@ const generateCreate: OpGen = (ctx, step, index) => {
   // Load data from test data file
   if (hasDatvar) {
     Content(`		${datavar} = core.ToMapAny(vs.GetProp(
-			vs.GetPath([]any{"new", "${entity.name}"}, setup.data), "${ref}"))
+			vs.GetPath(setup.data, []any{"new", "${entity.name}"}), "${ref}"))
 `)
   } else {
     Content(`		${datavar} := core.ToMapAny(vs.GetProp(
-			vs.GetPath([]any{"new", "${entity.name}"}, setup.data), "${ref}"))
+			vs.GetPath(setup.data, []any{"new", "${entity.name}"}), "${ref}"))
 `)
   }
 
@@ -606,7 +639,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
 `)
   }
   if (!hasSrcData && hasEntId) {
-    Content(`		${srcdatavar}Raw := vs.Items(core.ToMapAny(vs.GetPath("existing.${entity.name}", setup.data)))
+    Content(`		${srcdatavar}Raw := vs.Items(core.ToMapAny(vs.GetPath(setup.data, "existing.${entity.name}")))
 		var ${srcdatavar} map[string]any
 		if len(${srcdatavar}Raw) > 0 {
 			${srcdatavar} = core.ToMapAny(${srcdatavar}Raw[0][1])