@voxgig/sdkgen 4.34.0 → 4.34.1

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

@@ -95,7 +95,7 @@ object PrepareAuth {
   val CRED_NAME = "${scalastr(spec.name)}"
   val OPTION_APIKEY = "apikey"
 ${spec.basic ? `  val OPTION_SECRET = "secret"\n` : ''}  val NOT_FOUND = "__NOTFOUND__"
-
+${authName(true)}
   def prepareAuth(ctx: Context): Spec = {
     val spec = ctx.spec
     if (spec == null) throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
@@ -109,6 +109,13 @@ ${spec.basic ? `  val OPTION_SECRET = "secret"\n` : ''}  val NOT_FOUND = "__NOTF
       return spec
     }
 
+    val name = authName(options)
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (name != CRED_NAME) {
+      headers.remove(CRED_NAME)
+    }
+
     val apikey = Struct.getprop(options, OPTION_APIKEY, NOT_FOUND)
 ${basicBlock(spec)}
     var skip = false
@@ -119,15 +126,15 @@ ${basicBlock(spec)}
     }
 
     if (skip) {
-      headers.remove(CRED_NAME)
+      headers.remove(name)
     } else {
       var authPrefix = ""
       Struct.getpath(options, java.util.List.of("auth", "prefix")) match { case s: String => authPrefix = s; case _ => }
       val apikeyVal = apikey match { case s: String => s; case _ => "" }
       // A raw credential (empty prefix, e.g. an apiKey scheme) must go in
       // as-is; only a non-empty prefix (Bearer/Basic/OAuth) is space-joined.
-      if ("" == authPrefix) headers.put(CRED_NAME, apikeyVal)
-      else headers.put(CRED_NAME, authPrefix + " " + apikeyVal)
+      if ("" == authPrefix) headers.put(name, apikeyVal)
+      else headers.put(name, authPrefix + " " + apikeyVal)
     }
 
     spec
@@ -157,7 +164,7 @@ function basicBlock(spec: AuthSpec): string {
       val noSecret = secret == null || (secret match { case s: String => NOT_FOUND == s || "" == s; case _ => false })
 
       if (noApikey) {
-        headers.remove(CRED_NAME)
+        headers.remove(name)
       } else {
         var basicPrefix = ""
         Struct.getpath(options, java.util.List.of("auth", "prefix")) match { case s: String => basicPrefix = s; case _ => }
@@ -167,8 +174,8 @@ function basicBlock(spec: AuthSpec): string {
         // The joined, encoded pair is a wire form neither credential's own
         // registration covers.
         if (ctx.utility != null && ctx.utility.cleanAdd != null) ctx.utility.cleanAdd(ctx, b64)
-        if ("" == basicPrefix) headers.put(CRED_NAME, b64)
-        else headers.put(CRED_NAME, basicPrefix + " " + b64)
+        if ("" == basicPrefix) headers.put(name, b64)
+        else headers.put(name, basicPrefix + " " + b64)
       }
 
       return spec
@@ -188,7 +195,7 @@ object PrepareAuth {
   val CRED_NAME = "${scalastr(spec.name)}"
   val OPTION_APIKEY = "apikey"
   val NOT_FOUND = "__NOTFOUND__"
-
+${authName(false)}
   def prepareAuth(ctx: Context): Spec = {
     val spec = ctx.spec
     if (spec == null) throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
@@ -202,6 +209,13 @@ object PrepareAuth {
       return spec
     }
 
+    val name = authName(options)
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (name != CRED_NAME) {
+      query.remove(CRED_NAME)
+    }
+
     val apikey = Struct.getprop(options, OPTION_APIKEY, NOT_FOUND)
 
     var skip = false
@@ -212,14 +226,14 @@ object PrepareAuth {
     }
 
     if (skip) {
-      query.remove(CRED_NAME)
+      query.remove(name)
     } else {
       val apikeyVal = apikey match { case s: String => s; case _ => "" }
       // NO PREFIX IN A QUERY STRING. \`?${spec.name}=Bearer%20abc\` is not a
       // thing any API reads: the prefix is a header convention, so the
       // options auth.prefix is dropped here deliberately rather than
       // silently concatenated.
-      query.put(CRED_NAME, apikeyVal)
+      query.put(name, apikeyVal)
     }
 
     spec
@@ -243,21 +257,18 @@ object PrepareAuth {
   val CRED_NAME = "${scalastr(spec.name)}"
   val OPTION_APIKEY = "apikey"
   val NOT_FOUND = "__NOTFOUND__"
-
-  // The cookie header minus our own pair, every other cookie untouched.
-  private def without(headers: JMap[String, Object]): String = {
+${authName(false)}
+  // The cookie header minus the named pair, every other cookie untouched.
+  private def without(headers: JMap[String, Object], name: String): String = {
     val existing = headers.get(COOKIE_HEADER) match { case s: String => s; case _ => "" }
     if ("" == existing) return ""
 
-    val kept = existing.split(";").map(_.trim).filter { piece =>
-      "" != piece && CRED_NAME != piece && !piece.startsWith(CRED_NAME + "=")
-    }
-    kept.mkString("; ")
+    PrepareHeaders.cookieKeep(existing, Seq(name)).mkString("; ")
   }
 
-  // Set (a value) or remove (null) our pair, leaving the rest in place.
-  private def place(headers: JMap[String, Object], value: String): Unit = {
-    val rest = without(headers)
+  // Set (a value) or remove (null) the named pair, leaving the rest in place.
+  private def place(headers: JMap[String, Object], name: String, value: String): Unit = {
+    val rest = without(headers, name)
 
     if (value == null) {
       if ("" == rest) headers.remove(COOKIE_HEADER)
@@ -265,7 +276,7 @@ object PrepareAuth {
       return
     }
 
-    val pair = CRED_NAME + "=" + value
+    val pair = name + "=" + value
     if ("" == rest) headers.put(COOKIE_HEADER, pair)
     else headers.put(COOKIE_HEADER, rest + "; " + pair)
   }
@@ -279,10 +290,17 @@ object PrepareAuth {
 
     // Public APIs that need no auth omit the options.auth block entirely.
     if (options.get("auth") == null) {
-      place(headers, null)
+      place(headers, CRED_NAME, null)
       return spec
     }
 
+    val name = authName(options)
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (name != CRED_NAME) {
+      place(headers, CRED_NAME, null)
+    }
+
     val apikey = Struct.getprop(options, OPTION_APIKEY, NOT_FOUND)
 
     var skip = false
@@ -293,12 +311,12 @@ object PrepareAuth {
     }
 
     if (skip) {
-      place(headers, null)
+      place(headers, name, null)
     } else {
       val apikeyVal = apikey match { case s: String => s; case _ => "" }
       // NO PREFIX IN A COOKIE either - a cookie carries a bare
       // \`name=value\` pair, not a header's scheme-prefixed credential.
-      place(headers, apikeyVal)
+      place(headers, name, apikeyVal)
     }
 
     spec
@@ -308,6 +326,20 @@ object PrepareAuth {
 }
 
 
+// The client's `auth.name` option, when set, replaces the declared name; a
+// header name travels lower-cased.
+function authName(header: boolean): string {
+  return `
+  // The client's auth.name option, when set, replaces the name the API declares.
+  private def authName(options: Object): String =
+    Struct.getpath(options, java.util.List.of("auth", "name")) match {
+      case s: String if "" != s => ${header ? 's.toLowerCase(java.util.Locale.ROOT)' : 's'}
+      case _ => CRED_NAME
+    }
+`
+}
+
+
 function scalastr(s: string): string {
   return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
 }

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -29,6 +29,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(null, null)',    desc: 'List entities, optionally matching the given criteria.' },
   create: { method: 'create(data, null)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(data, null)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(data, null)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(match, null)', desc: 'Remove the matching entity.' },
 }
 
@@ -54,6 +55,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
@@ -112,7 +115,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       // The id key plus every REQUIRED match key (parent path params like
       // page_id) — the same shape the runtime resolves path params from, so
       // the example always works.
@@ -134,7 +137,7 @@ val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`scala
@@ -144,7 +147,7 @@ val ${eVar}List = client.${accessor}(null).list(null, null)
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear — including a
       // required id and parent keys like page_id — with a real literal.

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

@@ -39,7 +39,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'null'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `java.util.Map.of("${idF}", "test01")` : 'null'
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && ('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/scala/ReadmeInstall_scala.ts

@@ -38,11 +38,11 @@ cd scala && scala-cli compile .
   // dependency-free, plain-source scala-cli project (no sbt/mill build, no
   // third-party runtime deps), so install it from the git release tag or a
   // local source checkout and compile with scala-cli.
-  const { releasesUrl } = repoInfo(model)
+  const { hostName, tagsUrl } = repoInfo(model)
   Content(`This package is not yet published to Maven Central. The generated SDK is a
 plain-source scala-cli project (no build tool, no third-party runtime
-dependencies). Install it from the GitHub release tag
-(\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) or from a source
+dependencies). Install it from the ${hostName} release tag
+(\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})) or from a source
 checkout — compile it with scala-cli:
 
 \`\`\`bash

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import { scalaVarName } from './utility_scala'
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
-  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const info = modelText(model)
   const tagline = info.tagline || ''
 
   Content(`# ${model.Name} ${target.title} SDK
@@ -36,7 +36,7 @@ The ${target.title} SDK for the ${model.Name} API — an entity-oriented client
   // Model-driven op list — only the operations the active entities actually
   // expose (a read-only entity has just list+load); never claim
   // create/update/remove exist when no entity has them.
-  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {
     if (!e || e.active === false) return

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

@@ -28,9 +28,10 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     list: '| `list` | `(reqmatch, ctrl) -> Object` | List entities matching the criteria (an aggregate list). Raises on error. |',
     create: '| `create` | `(reqdata, ctrl) -> Object` | Create a new entity. Raises on error. |',
     update: '| `update` | `(reqdata, ctrl) -> Object` | Update an existing entity. Raises on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> Object` | Change part of an existing entity. Raises on error. |',
     remove: '| `remove` | `(reqmatch, ctrl) -> Object` | Remove an entity. Raises on error. |',
   }
-  const opRows = ['load', 'list', 'create', 'update', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
   const apikeyOptionRow = isAuthActive(model)

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

@@ -185,7 +185,8 @@ catch {
       return it && it.type
     }
 
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`scala
@@ -202,6 +203,14 @@ val created = client.${accessor}(null).create(java.util.Map.of(${examplePairs('c
         Content(`// Update — supply the id in the match/data
 client.${accessor}(null).update(java.util.Map.of(${updatePairs.join(', ')}), null)
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`"${idF}", ${scalaLit(idParamType('patch'), 'example_id')}`] : [])
+          .concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+client.${accessor}(null).patch(java.util.Map.of(${patchPairs.join(', ')}), null)
+
 `)
       }
       if (opnames.includes('remove')) {

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -45,6 +45,11 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
     returns: 'the updated entity data',
     desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
   },
+  patch: {
+    sig: 'patch(reqdata, ctrl) -> Object',
+    returns: 'the patched entity data',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity data and raises on error.',
+  },
   remove: {
     sig: 'remove(reqmatch, ctrl) -> Object',
     returns: 'the removed entity data',
@@ -217,7 +222,7 @@ val ${eVar} = client.${accessor}(null)
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
-          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
 
@@ -258,6 +263,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             const matchItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
@@ -298,8 +307,8 @@ val result = client.${accessor}(null).create(java.util.Map.of(
 
 `)
           }
-          else if ('update' === opname) {
-            const updateItems = opRequestShape(ent, 'update').items
+          else if ('update' === opname || 'patch' === opname) {
+            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))
@@ -309,12 +318,20 @@ val result = client.${accessor}(null).create(java.util.Map.of(
                 it.name === idF ? ent.name + '_id' : it.name)}${comma}\n`
             }).join('')
             Content(`\`\`\`scala
-val result = client.${accessor}(null).update(java.util.Map.of(
+val result = client.${accessor}(null).${opname}(java.util.Map.of(
 ${updateLines}), null)
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'an `Array[Byte]`, a `String` or an `InputStream`',
+              once: 'an `InputStream`',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

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

@@ -51,7 +51,7 @@ val client = ${SDK}.testSDK(null, null)
         ? `java.util.Map.of(${items.map((it: any) =>
           `"${it.name}", ${it.name === idF ? '"test01"' : scalaLit(it.type)}`).join(', ')})`
         : 'null'
-    } 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/scala/TestClean_scala.ts

@@ -227,8 +227,25 @@ object SdkCleanTestMain {
     }),
   )
 
+  // Offline, as every generated suite is: the test OPTION resolves a required
+  // server variable to test-<name>, and installs no transport.
+  private def offline(opts: JMap[String, Object]): JMap[String, Object] = {
+    val out = new LinkedHashMap[String, Object](opts)
+    out.put("test", om("active" -> B(true)))
+    out
+  }
+
+  // A client the sweep cannot build leaves nothing swept: a harness error, not
+  // a leak.
+  private def construct(opts: JMap[String, Object]): ${SDK} =
+    try new ${SDK}(offline(opts))
+    catch {
+      case e: RuntimeException => throw new IllegalStateException(
+        "clean harness: the client could not be constructed, so nothing was swept: " + e.getMessage, e)
+    }
+
   private def makeSdk(scenario: Scenario, sinks: ArrayList[Sink], cleanopts: JMap[String, Object],
-      extra: BaseFeature = null): ${SDK} = {
+      extra: BaseFeature = null, auth: JMap[String, Object] = null): ${SDK} = {
     def capture(name: String): Consumer[Object] = (rec: Object) => collect(sinks, name, rec)
 
     val feature = new LinkedHashMap[String, Object]()
@@ -267,7 +284,8 @@ object SdkCleanTestMain {
     if (extra != null) extend.add(extra)
     opts.put("extend", extend)
     opts.put("utility", om("fetcher" -> fetcher))
-    new ${SDK}(opts)
+    if (auth != null) opts.put("auth", auth)
+    construct(opts)
   }
 
   final class Target(val accessor: Method, val op: String, val matchArgs: JMap[String, Object])
@@ -293,6 +311,7 @@ object SdkCleanTestMain {
       case "load" => ent.load(args, ctrl)
       case "create" => ent.create(args, ctrl)
       case "update" => ent.update(args, ctrl)
+      case "patch" => ent.patch(args, ctrl)
       case "remove" => ent.remove(args, ctrl)
       case _ => throw new IllegalArgumentException("no such op: " + op)
     }
@@ -322,7 +341,7 @@ object SdkCleanTestMain {
   private def usableOp(): Target = {
     val plainFetch: (Context, String, JMap[String, Object]) => Object =
       (_, _, _) => response(200, om("id" -> "i1"), null)
-    val plain = new ${SDK}(om("apikey" -> CANARY_APIKEY, "utility" -> om("fetcher" -> plainFetch)))
+    val plain = construct(om("apikey" -> CANARY_APIKEY, "utility" -> om("fetcher" -> plainFetch)))
     val entities = Helpers.toMapAny(Config.sharedConfig().get("entity"))
     if (entities == null) return null
     val rank = Map("list" -> 0, "load" -> 1)
@@ -359,12 +378,15 @@ object SdkCleanTestMain {
   private def drive(sdk: ${SDK}, target: Target, ctrl: JMap[String, Object], sinks: ArrayList[Sink]): Throwable = {
     // A caller may keep the record it passed rather than read ctrl's entry.
     val held = if (ctrl == null) null else ctrl.get("explain")
+    val entity = entityOf(sdk, target.accessor)
     var out: Object = null
     var err: Throwable = null
-    try out = call(entityOf(sdk, target.accessor), target.op, target.matchArgs, ctrl)
+    try out = call(entity, target.op, target.matchArgs, ctrl)
     catch { case e: Throwable => err = e }
     if (err != null) collect(sinks, "error", err)
     if (out != null) collect(sinks, "result", out)
+    // Raw, as a caller copying the match into another query reads it.
+    if (entity != null) collect(sinks, "match", entity.matchArgs())
     val explain = if (ctrl == null) null else ctrl.get("explain")
     if (explain != null) collect(sinks, "explain", explain)
     if (held != null && !(held eq explain)) collect(sinks, "explain:held", held)
@@ -399,13 +421,17 @@ object SdkCleanTestMain {
       }
     }
 
+    // A name given at run time replaces the declared one: the match leaves
+    // out whichever name prepareAuth placed.
+    drive(makeSdk(SCENARIOS.head, sinks, null, auth = om("name" -> "zzcred")), target, null, sinks)
+
     // A credential mistyped as a map. Validation here collects its errors
     // rather than throwing, so there is no rejection to sweep: sweep the
     // client it built, an operation it runs, and a message quoting the value.
     val fetch404: (Context, String, JMap[String, Object]) => Object =
       (_, url, fetchdef) => SCENARIOS(1).respond(url, fetchdef)
-    val mistyped = new ${SDK}(om("apikey" -> om("value" -> CANARY_APIKEY),
-      "clean" -> om("values" -> CANARY_VALUE), "utility" -> om("fetcher" -> fetch404)))
+    val mistyped = new ${SDK}(offline(om("apikey" -> om("value" -> CANARY_APIKEY),
+      "clean" -> om("values" -> CANARY_VALUE), "utility" -> om("fetcher" -> fetch404))))
     collect(sinks, "mistyped", mistyped)
     drive(mistyped, target, null, sinks)
     collect(sinks, "mistyped:quoted",
@@ -535,13 +561,15 @@ object SdkCleanTestMain {
 
   // A feature's name is not a field name: only the sensitive names inside its
   // settings register. An entity block, of per-entity settings or seeded
-  // records keyed by entity name and id, is not read at all.
+  // records keyed by entity name and id, is not read at all, and nor are
+  // rbac's rules, keyed by entity and operation names.
   private def featureNames(rep: SdkTestReport): Unit = {
-    val sdk = new ${SDK}(om(
+    val sdk = construct(om(
       "apikey" -> CANARY_APIKEY,
       "feature" -> om(
         "zzsecrets" -> om("active" -> B(false), "kind" -> "PLAINSETTING-q8w2e4r6"),
         "zzfeat" -> om("active" -> B(false), "apitoken" -> "FEATTOKEN-z9y8x7w6"),
+        "rbac" -> om("active" -> B(false), "rules" -> om("zztoken.load" -> "PLAINRULE-k7j5h3g1")),
         "test" -> om("active" -> B(false), "entity" -> om(
           "zztoken" -> om("ZZTOKEN01" -> om("note" -> "PLAINRECORD-t5r3e1w9"))))),
       "entity" -> om("zztoken" -> om("alias" -> om("zzkey" -> "PLAINALIAS-m2n4b6v8")))))
@@ -551,10 +579,11 @@ object SdkCleanTestMain {
     rep.eq("clean.feature.token", "token " + MASK, clean("token FEATTOKEN-z9y8x7w6"))
     rep.eq("clean.entity.record", "record PLAINRECORD-t5r3e1w9", clean("record PLAINRECORD-t5r3e1w9"))
     rep.eq("clean.entity.alias", "alias PLAINALIAS-m2n4b6v8", clean("alias PLAINALIAS-m2n4b6v8"))
+    rep.eq("clean.rbac.rule", "rule PLAINRULE-k7j5h3g1", clean("rule PLAINRULE-k7j5h3g1"))
   }
 
   private def configBlock(rep: SdkTestReport): Unit = {
-    val utility = new ${SDK}(om()).getUtility()
+    val utility = construct(om()).getUtility()
     val config = om("options" -> om("clean" -> om("keys" -> "zzsens", "values" -> "CONFIG-SEEDED-1")))
     val ctx = utility.makeContext(om("utility" -> utility, "config" -> config,
       "options" -> om("clean" -> om("values" -> "CALLER-SEEDED-2"))), null)
@@ -569,7 +598,7 @@ object SdkCleanTestMain {
   }
 
   private def noBlock(rep: SdkTestReport): Unit = {
-    val utility = new ${SDK}(om()).getUtility()
+    val utility = construct(om()).getUtility()
     val ctx = utility.makeContext(om("utility" -> utility,
       "options" -> om("apikey" -> "NOBLOCK-APIKEY-k3j5h7")), null)
     ctx.options = utility.makeOptions(ctx)