@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/lua/ReadmeRef_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey, targetFeatures, opNeedsAction, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -14,6 +14,7 @@ import {
 // parse).
 function luaLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '{}'
@@ -27,27 +28,32 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   load: {
     sig: 'load(reqmatch, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Load a single entity matching the given criteria.',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get()` reads, or `nil` and an error on failure.',
   },
   list: {
     sig: 'list(reqmatch, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    desc: 'List entities matching the given criteria. Returns an array of entities, one per record, or `nil` and an error on failure.',
   },
   create: {
     sig: 'create(reqdata, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Create a new entity with the given data.',
+    desc: 'Create a new entity with the given data. Returns the created entity, or `nil` and an error on failure.',
   },
   update: {
     sig: 'update(reqdata, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity, or `nil` and an error on failure.',
+  },
+  patch: {
+    sig: 'patch(reqdata, ctrl) -> any, err',
+    returns: 'any, err',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity, or `nil` and an error on failure.',
   },
   remove: {
     sig: 'remove(reqmatch, ctrl) -> any, err',
     returns: 'any, err',
-    desc: 'Remove the entity matching the given criteria.',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, or `nil` and an error on failure.',
   },
 }
 
@@ -215,7 +221,7 @@ local ${eVar} = client:${ent.Name}(nil)
         if (hasFieldOps) {
           // Only emit columns for operations this entity actually exposes —
           // never advertise a create/update/remove column the entity lacks.
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -255,6 +261,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
             // like page_id) — the same shape the runtime resolves path
@@ -276,7 +286,7 @@ local result, err = client:${ent.Name}():${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`lua
-local results, err = client:${ent.Name}():list()
+local results, err = client:${ent.Name}():list(${listMatchArg('lua', ent)})
 \`\`\`
 
 `)
@@ -301,10 +311,10 @@ local result, err = client:${ent.Name}():create({
 
 `)
           }
-          else if ('update' === opname) {
+          else if ('update' === opname || 'patch' === opname) {
             // The id key plus every REQUIRED data member — the same shape the
             // runtime validates — then the patch-fields note.
-            const updateItems = opRequestShape(ent, 'update').items
+            const updateItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
@@ -312,13 +322,20 @@ local result, err = client:${ent.Name}():create({
               `  ${luaKey(it.name)} = ${luaLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`lua
-local result, err = client:${ent.Name}():update({
-${updateLines}  -- Fields to update
+local result, err = client:${ent.Name}():${opname}({
+${updateLines}  -- ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 })
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a string',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/lua/ReadmeTopQuick_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,7 @@ import {
 // doc test EXECUTES this block, so a comment placeholder would break it).
 function luaLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '{}'
@@ -33,9 +34,12 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
     ? `sdk.new({\n  apikey = os.getenv("${envName(model)}_APIKEY"),\n})`
     : `sdk.new()`
 
+  const shown = null != exampleEntity &&
+    ['list', 'load'].some((op: string) => Object.keys(exampleEntity.op || {}).includes(op))
+
   Content(`\`\`\`lua
 local sdk = require("${model.name}_sdk")
-
+${shown ? 'local json = require("dkjson")\n' : ''}
 local client = ${ctor}
 
 `)
@@ -51,9 +55,12 @@ local client = ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`-- List all ${eName.toLowerCase()}s
-local ${eVar}s, err = client:${eName}():list()
-print(${eVar}s)
+      Content(`-- List all ${eName.toLowerCase()}s (an array of entities, one per record; err on failure)
+local ${eVar}s, err = client:${eName}():list(${listMatchArg('lua', exampleEntity)})
+if err then error(err) end
+for _, ${eVar} in ipairs(${eVar}s) do
+  print(json.encode(${eVar}:data_get()))
+end
 `)
       hasCall = true
     }
@@ -72,9 +79,10 @@ print(${eVar}s)
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
         : ''
       Content(`
--- Load a specific ${eName.toLowerCase()}
+-- Load a specific ${eName.toLowerCase()} (returns the entity; err on failure)
 local ${eVar}, err = client:${eName}():load(${loadArg})
-print(${eVar})
+if err then error(err) end
+print(json.encode(${eVar}:data_get()))
 `)
       hasCall = true
     }

package/project/.sdk/src/cmp/lua/ReadmeTopTest_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, luaKey } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, luaKey, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,6 +11,7 @@ import {
 // A type-correct Lua literal for a field's canonical type.
 function luaLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '{}'
@@ -36,18 +37,18 @@ local client = sdk.test()
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = ''
-    if (isMatchOp) {
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
       // Every REQUIRED match key (id first, then parent path params like
       // page_id) — the same shape the runtime resolves path params from.
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+      const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF) : requiredItems(exampleEntity, 'list'))
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = 0 < items.length
         ? `{ ${items.map((it: any) =>
-          `${luaKey(it.name)} = ${it.name === idF ? '"test01"' : luaLit(it.type)}`).join(', ')} }`
+          `${luaKey(it.name)} = ${isMatchOp && it.name === idF ? '"test01"' : luaLit(it.type)}`).join(', ')} }`
         : ''
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)

package/project/.sdk/src/cmp/lua/TestClean_lua.ts

@@ -400,7 +400,31 @@ local function has_feature(name)
 end
 
 
-local function make_sdk(scenario, sinks, cleanopts, extra)
+-- Offline, as every generated suite is: the test OPTION resolves a required
+-- server variable to test-<name>, and installs no transport.
+local function offline(opts)
+  local out = {}
+  for k, v in pairs(opts) do
+    out[k] = v
+  end
+  out.test = { active = true }
+  return out
+end
+
+
+-- A client the sweep cannot build leaves nothing swept: a harness error, not
+-- a leak.
+local function construct(opts)
+  local ok, client = pcall(sdk.new, offline(opts))
+  if not ok then
+    error("clean harness: the client could not be constructed, so nothing was swept: " ..
+      tostring(client), 0)
+  end
+  return client
+end
+
+
+local function make_sdk(scenario, sinks, cleanopts, extra, auth)
   local function capture(name)
     return function(rec) append(sinks, surfaces(name, rec)) end
   end
@@ -442,7 +466,7 @@ local function make_sdk(scenario, sinks, cleanopts, extra)
     extend[#extend + 1] = f
   end
 
-  return sdk.new({
+  return construct({
     apikey = CANARY.apikey,
     secret = CANARY.secret,
     headers = { ["X-Custom-Token"] = CANARY.header },
@@ -452,6 +476,7 @@ local function make_sdk(scenario, sinks, cleanopts, extra)
     utility = {
       fetcher = function(_ctx, url, fetchdef) return scenario.respond(url, fetchdef) end,
     },
+    auth = auth,
   })
 end
 
@@ -459,7 +484,7 @@ end
 -- The first operation that completes against a plain 200: with no
 -- arguments, else with every path parameter its points declare filled in.
 local function usable_op()
-  local plain = sdk.new({
+  local plain = construct({
     apikey = CANARY.apikey,
     utility = { fetcher = function() return response(200, { id = "i1" }) end },
   })
@@ -530,6 +555,8 @@ local function drive(client, target, ctrl, sinks)
   if out ~= nil then
     append(sinks, surfaces("result", out))
   end
+  -- Raw, as a caller copying the match into another query reads it.
+  append(sinks, surfaces("match", ent:match_get()))
   if ctrl.explain ~= nil then
     append(sinks, surfaces("explain", ctrl.explain))
   end
@@ -573,12 +600,16 @@ describe("clean", function()
       end
     end
 
+    -- A name given at run time replaces the declared one: the match leaves
+    -- out whichever name prepare_auth placed.
+    drive(make_sdk(SCENARIOS[1], sinks, nil, nil, { name = "zzcred" }), target, {}, sinks)
+
     -- A credential mistyped as a table is rejected by validation, whose
     -- message quotes the value it rejected.
-    local built, rejected = pcall(sdk.new, {
+    local built, rejected = pcall(sdk.new, offline({
       apikey = { value = CANARY.apikey },
       clean = { values = CANARY.value },
-    })
+    }))
     assert.is_false(built, "a credential mistyped as a table should be rejected")
     append(sinks, surfaces("rejected", rejected))
 
@@ -604,13 +635,13 @@ describe("clean", function()
 
     -- Iterating a stream runs inside the same catch path as the operation,
     -- and the explain record the caller passed is cleaned however it ends.
-    -- A step's error ends a stream without raising. The caller stops at the
-    -- first item, leaving the stream open.
+    -- A step's error raises from the stream, as it fails the operation. The
+    -- caller stops at the first item, leaving the stream open.
     for _, case in ipairs({
       { name = "stream", extra = { StreamThrowFeature.new() }, raises = true },
       { name = "stream-ok", extra = { StreamOkFeature.new() } },
       { name = "stream-plain", extra = {} },
-      { name = "stream-step", extra = { StepFailFeature.new() } },
+      { name = "stream-step", extra = { StepFailFeature.new() }, raises = true },
     }) do
       local streamed = make_sdk(SCENARIOS[1], sinks, nil, case.extra)
       local sent = streamed[target.accessor](streamed)
@@ -628,7 +659,7 @@ describe("clean", function()
     end
 
     -- A client given no clean block at all masks by the schema defaults.
-    local bare = sdk.new({
+    local bare = construct({
       apikey = CANARY.apikey,
       secret = CANARY.secret,
       headers = { ["X-Custom-Token"] = CANARY.header },
@@ -727,12 +758,14 @@ describe("clean", function()
   -- A feature's name is not a field name: a feature called secrets does not
   -- make its settings secret, though a sensitive field inside it still is. An
   -- entity block, of per-entity settings or seeded records keyed by entity
-  -- name and id, is not read at all.
+  -- name and id, is not read at all, and nor are rbac's rules, keyed by entity
+  -- and operation names.
   it("a feature's name is read as a name", function()
-    local client = sdk.new({
+    local client = construct({
       apikey = CANARY.apikey,
       feature = {
         secrets = { active = false, name = "ZZNAME-feat123", token = "ZZTOKEN-feat456" },
+        rbac = { active = false, rules = { ["zztoken.load"] = "PLAINRULE-k7j5h3g1" } },
         test = { active = false, entity = { zztoken = { ZZTOKEN01 = { note = "PLAINRECORD-t5r3e1w9" } } } },
       },
       entity = { zztoken = { alias = { zzkey = "PLAINALIAS-m2n4b6v8" } } },
@@ -742,11 +775,12 @@ describe("clean", function()
     assert.are.equal("ZZNAME-feat123 " .. MASK, clean(ctx, "ZZNAME-feat123 ZZTOKEN-feat456"))
     assert.are.equal("record PLAINRECORD-t5r3e1w9", clean(ctx, "record PLAINRECORD-t5r3e1w9"))
     assert.are.equal("alias PLAINALIAS-m2n4b6v8", clean(ctx, "alias PLAINALIAS-m2n4b6v8"))
+    assert.are.equal("rule PLAINRULE-k7j5h3g1", clean(ctx, "rule PLAINRULE-k7j5h3g1"))
   end)
 
 
   it("the generated config's own clean block is honoured", function()
-    local utility = sdk.new({}):get_utility()
+    local utility = construct({}):get_utility()
     local config = { options = { clean = { keys = "zzsens", values = "CONFIG-SEEDED-1" } } }
     local opts = utility.make_options({
       utility = utility,

package/project/.sdk/src/cmp/lua/TestDirect_lua.ts

@@ -15,11 +15,26 @@ import {
   serverVarEnv,
   serverVariables,
   pointParts,
+  liveStrict,
+  liveStrictNote,
 } from '@voxgig/sdkgen'
 
 import { formatLuaValue } from './utility_lua'
 
 
+// Blocked without the ids its request needs, rather than sent with nil.
+function liveKeysBlock(keys: string[], entidEnvVar: string): string {
+  return 0 === keys.length ? '' : `    if setup.live then
+      for _, _live_key in ipairs({${keys.map((k) => JSON.stringify(k)).join(', ')}}) do
+        if setup.idmap[_live_key] == nil then
+          runner.live_miss(pending, LIVE_STRICT, "Live test blocked: needs " .. _live_key .. " via ${entidEnvVar}")
+        end
+      end
+    end
+`
+}
+
+
 function normalizePathParams(
   parts: string[],
   params: any[],
@@ -145,6 +160,10 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
+  // The *_ENTID key a live test reads a parameter's value from.
+  const liveKey = (param: any): string =>
+    ('id' === param.n ? entity.name : param.n.replace(/_id$/, '')) + '01'
+
   File({ name: entity.name + '_direct_test.' + target.ext }, () => {
 
     Content(`-- ${entity.Name} direct test
@@ -155,26 +174,21 @@ local sdk = require("${model.name}_sdk")
 local helpers = require("core.helpers")
 local runner = require("test.runner")
 
+${liveStrictNote(liveStrict(model, target.name), '--')}
+local LIVE_STRICT = ${liveStrict(model, target.name)}
+
+local function live_ok(result, err)
+  if err ~= nil or type(result) ~= "table" or result["err"] ~= nil or not result["ok"] then
+    return false
+  end
+  local status = helpers.to_int(result["status"])
+  return status >= 200 and status < 300
+end
+
 describe("${entity.Name}Direct", function()
 `)
 
     if (hasList && listPoint) {
-      const listLiveIdKeys: string[] = listParams.map((lp: any) => {
-        return lp.n === 'id'
-          ? entity.name + '01'
-          : lp.n.replace(/_id$/, '') + '01'
-      })
-      const listSkipBlock = listLiveIdKeys.length > 0
-        ? `    if setup.live then
-      for _, _live_key in ipairs({${listLiveIdKeys.map(k => `"${k}"`).join(', ')}}) do
-        if setup.idmap[_live_key] == nil then
-          pending("live test needs " .. _live_key .. " via *_ENTID env var (synthetic IDs only)")
-          return
-        end
-      end
-    end
-`
-        : ''
       Content(`  it("should direct-list-${entity.name}", function()
     local setup = ${entity.name}_direct_setup({
       { id = "direct01" },
@@ -185,58 +199,32 @@ describe("${entity.Name}Direct", function()
       pending(_reason or "skipped via sdk-test-control.json")
       return
     end
-${listSkipBlock}    local client = setup.client
-
-`)
+${liveKeysBlock(listParams.map(liveKey), entidEnvVar)}    local client = setup.client
 
-      if (listParams.length > 0) {
-        Content(`    local params = {}
+    local params = {}
 `)
-        for (const lp of listParams) {
-          const key = lp.n === 'id'
-            ? entity.name + '01'
-            : lp.n.replace(/_id$/, '') + '01'
-          Content(`    if setup.live then
-      params["${lp.n}"] = setup.idmap["${key}"]
+      listParams.forEach((lp: any, i: number) => {
+        Content(`    if setup.live then
+      params["${lp.n}"] = setup.idmap["${liveKey(lp)}"]
     else
-      params["${lp.n}"] = "direct01"
+      params["${lp.n}"] = "direct0${i + 1}"
     end
 `)
-        }
-        Content(`
+      })
+      Content(`
     local result, err = client:direct({
       path = "${listPath}",
       method = "GET",
       params = params,
     })
-`)
-      } else {
-        Content(`
-    local result, err = client:direct({
-      path = "${listPath}",
-      method = "GET",
-      params = {},
-    })
-`)
-      }
-
-      Content(`    if setup.live then
-      -- Live mode is lenient: synthetic IDs frequently 4xx and the list-
-      -- response shape varies wildly across public APIs. Skip rather than
-      -- fail when the call doesn't return a usable list.
-      if err ~= nil then
-        pending("list call failed (likely synthetic IDs against live API): " .. tostring(err))
-        return
-      end
-      if not result["ok"] then
-        pending("list call not ok (likely synthetic IDs against live API)")
-        return
+    if setup.live then
+      if not live_ok(result, err) then
+        runner.live_miss(pending, LIVE_STRICT, "Live list failed: " .. runner.live_describe(result, err))
       end
-      local status = helpers.to_int(result["status"])
-      if status < 200 or status >= 300 then
-        pending("expected 2xx status, got " .. tostring(status))
-        return
+      if runner.live_list(result["data"]) == nil then
+        runner.live_miss(pending, LIVE_STRICT, "Live list returned no list: " .. runner.live_describe(result, err))
       end
+      assert.is_table(runner.live_list(result["data"]))
     else
       assert.is_nil(err)
       assert.is_true(result["ok"])
@@ -251,13 +239,11 @@ ${listSkipBlock}    local client = setup.client
     }
 
     if (hasLoad && loadPoint) {
-      const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
-        ? `    if setup.live then
-      pending("live direct-load needs real ID — set *_ENTID env var with real IDs to run")
-      return
-    end
-`
-        : ''
+      const discover = !loadAllHaveExamples && hasList && 0 < loadParams.length
+      const idParam = loadParams.find((p: any) => 'id' === p.n)?.n ?? loadParams[0]?.n ?? 'id'
+      const loadLiveIdKeys: string[] = loadAllHaveExamples ? [] :
+        discover ? listParams.map(liveKey).concat(loadParams.filter((p: any) => idParam !== p.n).map(liveKey)) :
+          loadParams.map(liveKey)
       Content(`  it("should direct-load-${entity.name}", function()
     local setup = ${entity.name}_direct_setup({ id = "direct01" })
     local _should_skip, _reason = runner.is_control_skipped("direct", "direct-load-${entity.name}", setup.live and "live" or "unit")
@@ -265,82 +251,71 @@ ${listSkipBlock}    local client = setup.client
       pending(_reason or "skipped via sdk-test-control.json")
       return
     end
-${loadSkipBlock}    local client = setup.client
+${liveKeysBlock([...new Set(loadLiveIdKeys)], entidEnvVar)}    local client = setup.client
 
-`)
-
-      const needsQuery = loadParams.length > 0 || loadLiveQueryLines !== ''
-      if (needsQuery) {
-        Content(`    local params = {}
+    local params = {}
     local query = {}
+    if setup.live then
+${loadLiveQueryLines ? loadLiveQueryLines + '\n' : ''}`)
+      if (loadAllHaveExamples) {
+        Content(loadExampleLines + '\n')
+      }
+      else if (discover) {
+        Content(`      local list_result, list_err = client:direct({
+        path = "${listPath}",
+        method = "GET",
+        params = {${listParams.map((p: any) => `["${p.n}"] = setup.idmap["${liveKey(p)}"]`).join(', ')}},
+      })
+      if not live_ok(list_result, list_err) then
+        runner.live_miss(pending, LIVE_STRICT, "Live list discovery failed: " .. runner.live_describe(list_result, list_err))
+      end
+      local records = runner.live_list(list_result["data"])
+      if records == nil then
+        runner.live_miss(pending, LIVE_STRICT, "Live list discovery returned no list: " .. runner.live_describe(list_result, list_err))
+      end
+      if records[1] == nil then
+        runner.live_empty(pending, "The account has no ${entity.name} record to load")
+      end
+      local first = type(records[1]) == "table" and records[1] or {}
+      local found = first["${idParam}"] or first["id"]
+      if found == nil then
+        runner.live_miss(pending, LIVE_STRICT, "Live load blocked: discovery returned no usable identity")
+      end
+      params["${idParam}"] = found
 `)
-        if (loadAllHaveExamples) {
-          Content(`    if setup.live then
-`)
-          if (loadLiveQueryLines) Content(loadLiveQueryLines + '\n')
-          Content(loadExampleLines + '\n')
-          Content(`    else
-`)
-          for (let i = 0; i < loadParams.length; i++) {
-            Content(`      params["${loadParams[i].n}"] = "direct0${i + 1}"
-`)
-          }
-          Content(`    end
-`)
-        } else if (loadParams.length > 0) {
-          if (loadLiveQueryLines) {
-            Content(`    if setup.live then
-${loadLiveQueryLines}
-    end
+        for (const p of loadParams.filter((p: any) => idParam !== p.n)) {
+          Content(`      params["${p.n}"] = setup.idmap["${liveKey(p)}"]
 `)
-          }
-          Content(`    if not setup.live then
-`)
-          for (let i = 0; i < loadParams.length; i++) {
-            Content(`      params["${loadParams[i].n}"] = "direct0${i + 1}"
+        }
+      }
+      else {
+        for (const p of loadParams) {
+          Content(`      params["${p.n}"] = setup.idmap["${liveKey(p)}"]
 `)
-          }
-          Content(`    end
+        }
+      }
+      Content(`    else
 `)
-        } else if (loadLiveQueryLines) {
-          Content(`    if setup.live then
-${loadLiveQueryLines}
-    end
+      for (let i = 0; i < loadParams.length; i++) {
+        Content(`      params["${loadParams[i].n}"] = "direct0${i + 1}"
 `)
-        }
       }
+      Content(`    end
 
-      Content(`
     local result, err = client:direct({
       path = "${loadPath}",
       method = "GET",
-`)
-      if (needsQuery) {
-        Content(`      params = params,
+      params = params,
       query = query,
-`)
-      } else {
-        Content(`      params = {},
-`)
-      }
-      Content(`    })
+    })
     if setup.live then
-      -- Live mode is lenient: synthetic IDs frequently 4xx. Skip rather
-      -- than fail when the load endpoint isn't reachable with the IDs we
-      -- can construct from setup.idmap.
-      if err ~= nil then
-        pending("load call failed (likely synthetic IDs against live API): " .. tostring(err))
-        return
+      if not live_ok(result, err) then
+        runner.live_miss(pending, LIVE_STRICT, "Live load failed: " .. runner.live_describe(result, err))
       end
-      if not result["ok"] then
-        pending("load call not ok (likely synthetic IDs against live API)")
-        return
-      end
-      local status = helpers.to_int(result["status"])
-      if status < 200 or status >= 300 then
-        pending("expected 2xx status, got " .. tostring(status))
-        return
+      if result["data"] == nil then
+        runner.live_miss(pending, LIVE_STRICT, "Live load returned no data: " .. runner.live_describe(result, err))
       end
+      assert.is_not_nil(result["data"])
     else
       assert.is_nil(err)
       assert.is_true(result["ok"])
@@ -382,11 +357,12 @@ function ${entity.name}_direct_setup(mockres)
       end
     end
     local client = sdk.new(merged_opts)
+    local idmap = env["${entidEnvVar}"]
     return {
       client = client,
       calls = calls,
       live = true,
-      idmap = {},
+      idmap = type(idmap) == "table" and idmap or {},
     }
   end