@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/tm/kotlin/core/Helpers.kt

@@ -15,6 +15,14 @@ object Helpers {
     )
   }
 
+  // Whether a comma-separated allow option names the item: whole names, any case.
+  fun allowed(names: Any?, item: String?): Boolean {
+    if (names !is String || item.isNullOrEmpty()) {
+      return false
+    }
+    return names.split(",").any { it.trim().equals(item, ignoreCase = true) }
+  }
+
   @Suppress("UNCHECKED_CAST")
   fun toMapAny(v: Any?): MutableMap<String, Any?>? {
     if (v == null) {

package/project/.sdk/tm/kotlin/core/Interfaces.kt

@@ -25,6 +25,8 @@ interface SdkEntity : Entity {
 
   fun update(reqdata: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any?
 
+  fun patch(reqdata: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any?
+
   fun remove(reqmatch: MutableMap<String, Any?>?, ctrl: MutableMap<String, Any?>?): Any?
 
   // Runs `action` through the pipeline and returns a Sequence over result

package/project/.sdk/tm/kotlin/core/Response.kt

@@ -15,6 +15,9 @@ class Response(resmap: Map<String, Any?>?) {
   var body: Any? = null
   var err: RuntimeException? = null
 
+  // Set by a transport that could not read a non-blank body as JSON.
+  var unreadable: Boolean = false
+
   init {
     val s = Struct.getprop(resmap, "status")
     if (s is Number) {
@@ -39,5 +42,67 @@ class Response(resmap: Map<String, Any?>?) {
     if (e is RuntimeException) {
       this.err = e
     }
+
+    this.unreadable = true == Struct.getprop(resmap, "unreadable")
+  }
+
+  companion object {
+    private const val PREVIEW_LENGTH = 160
+
+    /**
+     * A body that is not JSON. An HTTP failure keeps its own error, with the
+     * response described; otherwise the code tells a wrong content type from
+     * malformed JSON.
+     */
+    fun unreadableBody(
+      ctx: Context,
+      status: Int,
+      headers: Any?,
+      text: Any?,
+      sent: Any?,
+      failed: RuntimeException?,
+    ): RuntimeException {
+      val type = headerValue(headers, "content-type")
+      val agent = clean(ctx, headerValue(sent, "user-agent")).ifEmpty { "transport default" }
+      val detail = "HTTP " + status + ", content-type " + type.ifEmpty { "none" } +
+        ", user-agent " + agent + (if (text == null) "" else ", body: " + preview(ctx, text))
+
+      if (failed != null) {
+        if (failed is SdkError) {
+          failed.msg += " ($detail)"
+          return failed
+        }
+        return RuntimeException(failed.message + " ($detail)", failed)
+      }
+
+      if (type.isEmpty() || type.lowercase().contains("json")) {
+        return ctx.makeError("response_json_invalid", "response: body is not valid JSON ($detail)")
+      }
+      return ctx.makeError("response_content_type", "response: expected JSON, got $type ($detail)")
+    }
+
+    private fun headerValue(headers: Any?, name: String): String {
+      if (headers !is Map<*, *>) {
+        return ""
+      }
+      for ((k, v) in headers) {
+        if (name.equals(k.toString(), ignoreCase = true)) {
+          return v.toString()
+        }
+      }
+      return ""
+    }
+
+    private fun clean(ctx: Context, s: String): String =
+      ctx.utility?.clean?.invoke(ctx, s)?.toString() ?: s
+
+    // Cleaned whole: a secret the bound would split could leave its prefix.
+    private fun preview(ctx: Context, text: Any): String {
+      val flat = clean(ctx, text.toString().replace(Regex("\\s+"), " ").trim())
+      if (flat.codePointCount(0, flat.length) <= PREVIEW_LENGTH) {
+        return flat
+      }
+      return flat.substring(0, flat.offsetByCodePoints(0, PREVIEW_LENGTH)) + "..."
+    }
   }
 }

package/project/.sdk/tm/kotlin/core/SdkClient.kt

@@ -126,6 +126,14 @@ abstract class SdkClient(sdkopts: MutableMap<String, Any?>?) {
     if ("" == method) {
       method = "GET"
     }
+    method = method.uppercase()
+
+    val allowMethod = Struct.getpath(options, listOf("allow", "method"))
+    if (!Helpers.allowed(allowMethod, method)) {
+      throw ctx.makeError("spec_method_allow",
+        "Method \"" + method + "\" not allowed by SDK option allow.method value: \"" +
+          ((allowMethod as? String) ?: "") + "\"")
+    }
 
     var params = Helpers.toMapAny(Struct.getprop(fetchargs, "params"))
     if (params == null) {
@@ -179,8 +187,7 @@ abstract class SdkClient(sdkopts: MutableMap<String, Any?>?) {
 
   // Is this raw-access op permitted by the SDK's allow.op option?
   private fun opAllowed(op: String): Boolean {
-    val allow = Struct.getpath(this.options, listOf("allow", "op"))
-    return allow is String && allow.contains(op)
+    return Helpers.allowed(Struct.getpath(this.options, listOf("allow", "op")), op)
   }
 
   private fun opDenied(op: String): MutableMap<String, Any?> {
@@ -311,18 +318,28 @@ abstract class SdkClient(sdkopts: MutableMap<String, Any?>?) {
       val noBody = status == 204 || status == 304 || "0" == contentLength
 
       var jsonData: Any? = null
+      var bodyErr: RuntimeException? = null
       if (!noBody) {
         val jf = Struct.getprop(fm, "json")
         if (jf is Supplier<*>) {
           // The supplier returns null on parse error in our fetcher.
           jsonData = (jf as Supplier<Any?>).get()
         }
+        if (true == Struct.getprop(fm, "unreadable")) {
+          val failed = if (status in 200..299) null else ctx.makeError(
+            "request_status", "request: " + status + ": " + Struct.getprop(fm, "statusText"))
+          bodyErr = Response.unreadableBody(ctx, status, headers, Struct.getprop(fm, "body"),
+            fetchdef["headers"], failed)
+        }
       }
 
-      out["ok"] = status in 200..299
+      out["ok"] = bodyErr == null && status in 200..299
       out["status"] = status
       out["headers"] = headers
       out["data"] = jsonData
+      if (bodyErr != null) {
+        out["err"] = utility.clean(ctx, bodyErr)
+      }
       return out
     }
 

package/project/.sdk/tm/kotlin/core/Spec.kt

@@ -17,6 +17,9 @@ class Spec(specmap: Map<String, Any?>? = null) {
   var body: Any? = null
   var url: String = ""
   var path: String = ""
+  // The query parameters prepareAuth placed: the credential, which the
+  // request sends and the entity's match leaves out.
+  var authquery: MutableList<String> = mutableListOf()
 
   init {
     if (specmap != null) {

package/project/.sdk/tm/kotlin/feature/TestFeature.kt

@@ -59,9 +59,29 @@ class TestFeature : BaseFeature("test", "0.0.1", true) {
   // and the response transform unwraps that key on the way back. Returning the
   // bare payload means the transform unwraps a property that is not there and
   // the caller gets nothing. Mirrors the go/ts/lua/php mocks.
+  // The record the mock keeps: the request data without `$body`, which only the
+  // wire carries.
+  private fun record(reqdata: Map<String, Any?>?): MutableMap<String, Any?>? {
+    if (reqdata == null) return null
+    val out = LinkedHashMap(reqdata)
+    out.remove("\$body")
+    return out
+  }
+
+  // The key a list's response transform
+  // ["`$EACH`", "body", {"`$MERGE`": "`.<key>`"}] reads each item's record under.
+  private fun itemEnvelopeKey(restf: Any?): String? {
+    val spec = restf as? List<*> ?: return null
+    if (3 != spec.size || "`\$EACH`" != spec[0] || "body" != spec[1]) return null
+    val merge = (spec[2] as? Map<*, *>)?.get("`\$MERGE`") as? String ?: return null
+    return Regex("^`\\.([^.`\$]+)`\$").matchEntire(merge)?.groupValues?.get(1)
+  }
+
   private fun envelope(ctx: Context?, data: Any?): Any? {
     if (null == data || null == ctx) return data
     val tm = Struct.getprop(ctx.point, "transform")
+    val key = itemEnvelopeKey(Struct.getprop(tm, "res"))
+    if (null != key && data is List<*>) return data.map { linkedMapOf<String, Any?>(key to it) }
     val restf = Struct.getprop(tm, "res") as? String ?: return data
     // Rebuild whatever nesting the transform unwraps. Multi-segment on purpose:
     // GraphQL ops unwrap `body.data.<field>`, not just one envelope property.
@@ -139,7 +159,7 @@ class TestFeature : BaseFeature("test", "0.0.1", true) {
         val out = Struct.clone(found)
         return respond(ctx, 200, out, null)
       }
-      "update" -> {
+      "update", "patch" -> {
         // Match the existing entity by id only (or its alias).
         var updateMatch: MutableMap<String, Any?> = linkedMapOf()
         val reqdata = ctx.reqdata
@@ -166,7 +186,7 @@ class TestFeature : BaseFeature("test", "0.0.1", true) {
           return respond(ctx, 404, null, extra("statusText", "Not found"))
         }
         if (ent is MutableMap<*, *>) {
-          Struct.merge(Struct.jt(ent, reqdata))
+          Struct.merge(Struct.jt(ent, record(reqdata)))
         }
         Struct.delprop(ent, "\$KEY")
         val out = Struct.clone(ent)
@@ -195,7 +215,7 @@ class TestFeature : BaseFeature("test", "0.0.1", true) {
           )
         }
 
-        val ent = Struct.clone(ctx.reqdata)
+        val ent = Struct.clone(record(ctx.reqdata))
         if (ent is MutableMap<*, *>) {
           val entm = ent as MutableMap<String, Any?>
           entm["id"] = id

package/project/.sdk/tm/kotlin/feature/TimeoutFeature.kt

@@ -5,6 +5,7 @@ import java.util.concurrent.CompletionException
 import java.util.concurrent.ExecutionException
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.TimeoutException
+import java.util.concurrent.atomic.AtomicLong
 
 import KOTLINPACKAGE.core.Context
 import KOTLINPACKAGE.core.FetcherFn
@@ -42,31 +43,57 @@ class TimeoutFeature : BaseFeature("timeout", "0.0.1", true) {
       return inner(ctx, url, fetchdef)
     }
 
-    val fut: CompletableFuture<Any?> = CompletableFuture.supplyAsync { inner(ctx, url, fetchdef) }
+    // The deadline runs from here, not from the wait below: a caller paused
+    // between the two would otherwise find a late response complete and take
+    // it. The worker notes when it finished, so a response or a failure after
+    // the deadline is a timeout however late the caller looks.
+    val now = FeatureOptions.foptNow(this.options)
+    val start = now.asLong
+    val arrived = AtomicLong(Long.MAX_VALUE)
+    val fut: CompletableFuture<Any?> = CompletableFuture.supplyAsync {
+      try {
+        inner(ctx, url, fetchdef)
+      } finally {
+        arrived.set(now.asLong)
+      }
+    }
 
     try {
-      return fut.get(deadline.toLong(), TimeUnit.MILLISECONDS)
-    } catch (e: TimeoutException) {
-      track(deadline)
-      throw ctx.makeError("timeout", "Request exceeded timeout of ${deadline}ms")
-    } catch (e: ExecutionException) {
-      var cause: Throwable? = e.cause
-      if (cause is CompletionException && cause.cause != null) {
-        cause = cause.cause
+      val remaining = maxOf(0L, deadline - (now.asLong - start))
+      val out = try {
+        fut.get(remaining, TimeUnit.MILLISECONDS)
+      } catch (e: ExecutionException) {
+        if (deadline < arrived.get() - start) {
+          throw timeout(ctx, deadline)
+        }
+        throw unwrap(e)
       }
-      if (cause is RuntimeException) {
-        throw cause
+      if (deadline < arrived.get() - start) {
+        throw timeout(ctx, deadline)
       }
-      if (cause is Error) {
-        throw cause
-      }
-      throw RuntimeException(cause)
+      return out
+    } catch (e: TimeoutException) {
+      throw timeout(ctx, deadline)
     } catch (e: InterruptedException) {
       Thread.currentThread().interrupt()
       throw RuntimeException(e)
     }
   }
 
+  private fun unwrap(e: ExecutionException): Throwable {
+    var cause: Throwable? = e.cause
+    if (cause is CompletionException && cause.cause != null) {
+      cause = cause.cause
+    }
+    val found = cause
+    return if (found is RuntimeException || found is Error) found else RuntimeException(found)
+  }
+
+  private fun timeout(ctx: Context, deadline: Int): Throwable {
+    track(deadline)
+    return ctx.makeError("timeout", "Request exceeded timeout of ${deadline}ms")
+  }
+
   private fun track(deadline: Int) {
     this.count++
     this.ms = deadline

package/project/.sdk/tm/kotlin/feature/ValidateFeature.kt

@@ -184,6 +184,8 @@ class ValidateFeature : BaseFeature("validate", "0.0.1", true) {
     // fields will never name it - and under `strict` every custom-action call
     // would be rejected for the one key that made it reachable.
     out.remove("\$action")
+    // Nor is `$body`, the raw request body.
+    out.remove("\$body")
 
     return out
   }

package/project/.sdk/tm/kotlin/test/ConcurrencyTest.kt

@@ -0,0 +1,193 @@
+package KOTLINPACKAGE.sdktest
+
+// Requests in flight at once on one client. Each resolves its operation
+// through the cache the client's root context shares with every request, and
+// registers and cleans secrets through the one registry the client holds.
+
+import java.util.concurrent.ConcurrentLinkedQueue
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.CyclicBarrier
+import java.util.function.BiFunction
+import java.util.function.Supplier
+
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertSame
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Operation
+import KOTLINPACKAGE.core.ProjectNameSDK
+import KOTLINPACKAGE.core.Utility
+
+class ConcurrencyTest {
+
+  private val rounds = 200
+  private val width = 8
+  private val ops = 32
+
+  // A live client whose transport answers at once.
+  private fun liveClient(): ProjectNameSDK {
+    val fetch = BiFunction<String, MutableMap<String, Any?>, MutableMap<String, Any?>> { _, _ ->
+      linkedMapOf<String, Any?>(
+        "status" to 200,
+        "statusText" to "OK",
+        "headers" to linkedMapOf<String, Any?>(),
+        "json" to Supplier<Any?> { linkedMapOf<String, Any?>("ok" to true) },
+      )
+    }
+    return ProjectNameSDK(linkedMapOf<String, Any?>(
+      "base" to "http://concurrency.test/api",
+      "allow" to linkedMapOf<String, Any?>("op" to "direct"),
+      "system" to linkedMapOf<String, Any?>("fetch" to fetch),
+    ))
+  }
+
+  // Runs body on `width` threads released together, and returns what they threw.
+  private fun atOnce(body: (Int) -> Unit): List<Throwable> {
+    val start = CyclicBarrier(width)
+    val thrown = ConcurrentLinkedQueue<Throwable>()
+    val threads = (0 until width).map { n ->
+      Thread {
+        try {
+          start.await()
+          body(n)
+        } catch (t: Throwable) {
+          thrown.add(t)
+        }
+      }.also { it.start() }
+    }
+    threads.forEach { it.join() }
+    return thrown.toList()
+  }
+
+  @Test
+  fun concurrentFirstRequestsSucceed() {
+    repeat(rounds) { round ->
+      // A fresh client each round, so every request in it is a first request.
+      val client = liveClient()
+      val results = arrayOfNulls<MutableMap<String, Any?>>(width)
+      val thrown = atOnce { n -> results[n] = client.direct(linkedMapOf<String, Any?>("path" to "p$n")) }
+
+      assertTrue(thrown.isEmpty(), "round $round threw: $thrown")
+      results.forEachIndexed { n, res ->
+        assertEquals(true, res?.get("ok"), "round $round, request $n failed: $res")
+      }
+    }
+  }
+
+  @Test
+  fun concurrentResolutionsShareOneCachedOperation() {
+    repeat(rounds) { round ->
+      val client = liveClient()
+      val utility = client.getUtility()
+      val root = client.getRootCtx()
+      val got = Array(width) { arrayOfNulls<Operation>(ops) }
+      val thrown = atOnce { n ->
+        for (k in 0 until ops) {
+          got[n][k] = utility.makeContext(linkedMapOf<String, Any?>("opname" to "op$k"), root).op
+        }
+      }
+
+      assertTrue(thrown.isEmpty(), "round $round threw: $thrown")
+      for (k in 0 until ops) {
+        val cached = utility.makeContext(linkedMapOf<String, Any?>("opname" to "op$k"), root).op
+        for (n in 0 until width) {
+          assertSame(cached, got[n][k], "round $round: op$k resolved to more than one Operation")
+        }
+      }
+    }
+  }
+
+  private fun addedSecret(round: Int, n: Int, k: Int) = "ADDED-SECRET-$round-$n-$k"
+
+  // Registers thread n's secrets, then counts the thread out of registering.
+  private fun registerSecrets(
+    utility: Utility, root: Context, round: Int, n: Int, registering: CountDownLatch,
+  ) {
+    try {
+      for (k in 0 until ops) {
+        utility.cleanAdd(root, addedSecret(round, n, k))
+      }
+    } finally {
+      registering.countDown()
+    }
+  }
+
+  private fun assertEverySecretMasked(utility: Utility, root: Context, round: Int) {
+    for (n in 0 until width / 2) {
+      for (k in 0 until ops) {
+        val added = addedSecret(round, n, k)
+        assertEquals("[redacted]", utility.clean(root, added),
+          "round $round: $added was registered but not masked")
+      }
+    }
+  }
+
+  // Secrets registered on some threads while others clean: every clean masks
+  // what was registered before it, the longer secret whole, and no
+  // registration is lost.
+  @Test
+  fun concurrentRegistrationKeepsEverySecretMasked() {
+    repeat(rounds / 4) { round ->
+      val client = liveClient()
+      val utility = client.getUtility()
+      val root = client.getRootCtx()
+      val inner = "INNER-SECRET-$round"
+      utility.cleanAdd(root, inner)
+      utility.cleanAdd(root, "OUTER-$inner-TAIL")
+      val text = "a $inner b OUTER-$inner-TAIL c"
+      val masked = "a [redacted] b [redacted] c"
+      assertEquals(masked, utility.clean(root, text))
+
+      val registering = CountDownLatch(width / 2)
+      val wrong = ConcurrentLinkedQueue<Any?>()
+      val thrown = atOnce { n ->
+        if (n < width / 2) {
+          registerSecrets(utility, root, round, n, registering)
+        } else {
+          while (0L < registering.count) {
+            val cleaned = utility.clean(root, text)
+            if (masked != cleaned) {
+              wrong.add(cleaned)
+            }
+          }
+        }
+      }
+
+      assertTrue(thrown.isEmpty(), "round $round threw: $thrown")
+      assertTrue(wrong.isEmpty(), "round $round cleaned to: $wrong")
+      assertEverySecretMasked(utility, root, round)
+    }
+  }
+
+  // Requests on one client while secrets register on it: each request copies
+  // the client's options, the registry among them.
+  @Test
+  fun concurrentRequestsSurviveRegistration() {
+    repeat(rounds / 4) { round ->
+      val client = liveClient()
+      val utility = client.getUtility()
+      val root = client.getRootCtx()
+      val registering = CountDownLatch(width / 2)
+      val failed = ConcurrentLinkedQueue<Any?>()
+      val thrown = atOnce { n ->
+        if (n < width / 2) {
+          registerSecrets(utility, root, round, n, registering)
+        } else {
+          while (0L < registering.count) {
+            val res = client.direct(linkedMapOf<String, Any?>("path" to "p$n"))
+            if (true != res["ok"]) {
+              failed.add(res)
+              break
+            }
+          }
+        }
+      }
+
+      assertTrue(thrown.isEmpty(), "round $round threw: $thrown")
+      assertTrue(failed.isEmpty(), "round $round, a request failed: $failed")
+      assertEverySecretMasked(utility, root, round)
+    }
+  }
+}

package/project/.sdk/tm/kotlin/test/FeatureHarness.kt

@@ -142,7 +142,7 @@ object FeatureHarness {
   fun fhDefaultMethod(op: String): String {
     return when (op) {
       "create" -> "POST"
-      "update" -> "PATCH"
+      "update", "patch" -> "PATCH"
       "remove" -> "DELETE"
       else -> "GET"
     }

package/project/.sdk/tm/kotlin/test/FeatureTest.kt

@@ -274,6 +274,38 @@ class FeatureTest {
     assertEquals(1, f.count, "expected 1 timeout")
   }
 
+  // The deadline runs from the request's start, not from the wait: a response
+  // that arrives after it is a timeout even when the caller only looks once it
+  // is complete. The clock stands at the start for the caller and 300 ms
+  // later for the worker.
+  @Test
+  fun timeout_lateResponseTimesOutHoweverLateTheCallerLooks() {
+    assumeFeatures("timeout")
+    val f = TimeoutFeature()
+    val h = fhMake(null, fhF(f, fhMap("ms", 20, "now", workerClock(300L))))
+    val res = h.op(fhOp("load"))
+    assertEquals("timeout", fhErrCode(res.err), "expected timeout error, got ${res.err}")
+    assertEquals(1, f.count, "expected 1 timeout")
+  }
+
+  // A transport failure after the deadline is a timeout too, not the failure.
+  @Test
+  fun timeout_lateFailureTimesOut() {
+    assumeFeatures("timeout")
+    val f = TimeoutFeature()
+    val h = fhMake({ _, _, _ -> throw IllegalStateException("socket closed") },
+      fhF(f, fhMap("ms", 20, "now", workerClock(300L))))
+    val res = h.op(fhOp("load"))
+    assertEquals("timeout", fhErrCode(res.err), "expected timeout error, got ${res.err}")
+    assertEquals(1, f.count, "expected 1 timeout")
+  }
+
+  // A clock standing at 0 for the calling thread and at `later` for any other.
+  private fun workerClock(later: Long): LongSupplier {
+    val caller = Thread.currentThread()
+    return LongSupplier { if (Thread.currentThread() === caller) 0L else later }
+  }
+
   @Test
   fun timeout_fastRequestPasses() {
     assumeFeatures("timeout")

package/project/.sdk/tm/kotlin/test/RunnerSupport.kt

@@ -287,6 +287,96 @@ object RunnerSupport {
     return SdkError(code, msg, null)
   }
 
+  // A live check that did not pass, as main.kit.test.live.strict decides:
+  // strict fails the test, lenient skips it with the same reason.
+  fun liveMiss(strict: Boolean, reason: String) {
+    if (strict) {
+      org.junit.jupiter.api.Assertions.fail<Unit>(reason)
+    }
+    org.junit.jupiter.api.Assumptions.abort<Unit>(reason)
+  }
+
+  // An account holding no record for the test to read skips either way.
+  fun liveEmpty(reason: String) {
+    org.junit.jupiter.api.Assumptions.abort<Unit>(reason)
+  }
+
+  // A live list response's records: the body, or the first list an
+  // envelope holds.
+  fun liveList(data: Any?): List<Any?>? {
+    if (data is List<*>) {
+      return data as List<Any?>
+    }
+    if (data is Map<*, *>) {
+      for (value in TreeMap(data as Map<String, Any?>).values) {
+        if (value is List<*>) {
+          return value as List<Any?>
+        }
+      }
+    }
+    return null
+  }
+
+  // A live response for a message: the SDK's error, or else its status and
+  // content type, never its body.
+  fun liveDescribe(result: Map<String, Any?>?): String {
+    if (result == null) {
+      return "no response"
+    }
+    val err = result["err"]
+    if (err is Throwable) {
+      return err.message ?: err.toString()
+    }
+    if (err != null) {
+      return err.toString()
+    }
+    var out = "HTTP " + result["status"]
+    val headers = result["headers"]
+    if (headers is Map<*, *>) {
+      for ((k, v) in headers) {
+        if ("content-type".equals(k.toString(), ignoreCase = true) && v != null) {
+          out += " " + v.toString().split(";")[0].trim()
+        }
+      }
+    }
+    return out
+  }
+
+  // The record a create-less flow reads live: the first its list returns,
+  // put where the flow reads the fixture's existing records.
+  fun liveExisting(data: MutableMap<String, Any?>, strict: Boolean, name: String, list: () -> Any?) {
+    var found: Any? = null
+    try {
+      found = list()
+    } catch (e: RuntimeException) {
+      liveMiss(strict, "Live list discovery failed: " + e.message)
+    }
+    if (found !is List<*>) {
+      liveMiss(strict, "Live list discovery returned no list")
+    }
+    val items = found as List<Any?>
+    if (items.isEmpty()) {
+      liveEmpty("The account has no " + name + " record to load")
+    }
+    val first = items[0]
+    val record = if (first is Entity) first.data() else first
+    var existing = data["existing"]
+    if (existing !is MutableMap<*, *>) {
+      existing = linkedMapOf<String, Any?>()
+      data["existing"] = existing
+    }
+    (existing as MutableMap<String, Any?>)[name] = linkedMapOf<String, Any?>("live01" to record)
+  }
+
+  // In a lenient live run a failing check skips, observing the live API.
+  fun liveObserve(err: Throwable, live: Boolean, strict: Boolean) {
+    if (strict || !live || err is org.opentest4j.TestAbortedException) {
+      throw err
+    }
+    org.junit.jupiter.api.Assumptions.abort<Unit>(
+      "live run, main.kit.test.live.strict is false: " + err.message)
+  }
+
   // entityListToData extracts data maps from a list of Entity objects.
   fun entityListToData(list: List<Any?>?): MutableList<Any?> {
     val out = mutableListOf<Any?>()