@voxgig/sdkgen 4.34.0 → 4.34.2

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, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote, javaMap, javaMapOf } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -7,48 +7,41 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { scalaVarName } from './utility_scala'
+import { scalaVarName, scalaListMatch, scalaLit } from './utility_scala'
 
 
 // Type names come from the shared canonToType 'scala' column (single source of truth).
 
-// A type-correct Scala literal for a field's canonical type.
-function scalaLit(type: any, placeholder: string = 'example'): string {
-  const k = canonScalarKey(type)
-  if ('INTEGER' === k) return '1L'
-  if ('NUMBER' === k) return '1.0'
-  if ('BOOLEAN' === k) return 'true'
-  if ('ARRAY' === k) return 'java.util.List.of()'
-  if ('OBJECT' === k) return 'java.util.Map.of()'
-  return `"${placeholder}"`
-}
-
-
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, ctrl) -> Object',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data()` reads, and raises on error.',
   },
   list: {
     sig: 'list(reqmatch, ctrl) -> Object',
-    returns: 'an aggregate list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list(null, null)` to list all records. Returns an aggregate list and raises on error.',
+    returns: 'a list of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call `list(null, null)` to list all records. Returns a list of entities, one per record, and raises on error.',
   },
   create: {
     sig: 'create(reqdata, ctrl) -> Object',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and raises on error.',
   },
   update: {
     sig: 'update(reqdata, ctrl) -> Object',
-    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.',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and raises on error.',
+  },
+  patch: {
+    sig: 'patch(reqdata, ctrl) -> Object',
+    returns: 'the patched entity',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity and raises on error.',
   },
   remove: {
     sig: 'remove(reqmatch, ctrl) -> Object',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
 
@@ -217,7 +210,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,15 +251,19 @@ ${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)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
             const arg = 0 < matchItems.length
-              ? `java.util.Map.of(${matchItems.map((it: any) =>
+              ? javaMapOf(matchItems.map((it: any) =>
                 `"${it.name}", ${scalaLit(it.type,
-                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')})`
+                  it.name === idF ? ent.name + '_id' : it.name)}`), 'java.util.')
               : 'null'
             Content(`\`\`\`scala
 val result = client.${accessor}(null).${opname}(${arg}, null)
@@ -276,8 +273,8 @@ val result = client.${accessor}(null).${opname}(${arg}, null)
           }
           else if ('list' === opname) {
             Content(`\`\`\`scala
-val results = client.${accessor}(null).list(null, null)
-println(results)
+val results = client.${accessor}(null).list(${scalaListMatch(ent)}, null).asInstanceOf[java.util.List[SdkEntity]]
+results.forEach(item => println(item.data()))
 \`\`\`
 
 `)
@@ -285,12 +282,13 @@ println(results)
           else if ('create' === opname) {
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
+            const createMap = javaMap(createItems.length, 'java.util.')
             Content(`\`\`\`scala
-val result = client.${accessor}(null).create(java.util.Map.of(
+val result = client.${accessor}(null).create(${createMap.open}
 `)
             createItems.map((it: any, i: number) => {
               const comma = i < createItems.length - 1 ? ',' : ''
-              Content(`    "${it.name}", ${scalaLit(it.type, 'example_' + it.name)}${comma}  // ${canonToType(it.type, target.name)}
+              Content(`    ${createMap.pair(`"${it.name}", ${scalaLit(it.type, 'example_' + it.name)}`)}${comma}  // ${canonToType(it.type, target.name)}
 `)
             })
             Content(`), null)
@@ -298,23 +296,32 @@ 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))
+            const updateMap = javaMap(updateItems.length, 'java.util.')
             const updateLines = updateItems.map((it: any, i: number) => {
               const comma = i < updateItems.length - 1 ? ',' : ''
-              return `    "${it.name}", ${scalaLit(it.type,
-                it.name === idF ? ent.name + '_id' : it.name)}${comma}\n`
+              return `    ${updateMap.pair(`"${it.name}", ${scalaLit(it.type,
+                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}(${updateMap.open}
 ${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/ReadmeTopQuick_scala.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,21 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { scalaVarName, scalaPackage } from './utility_scala'
-
-
-// A type-correct Scala literal for a param: numeric/boolean/array/object params
-// render a typed literal; strings render the quoted placeholder. The SDK's
-// loose object model means all values live in java.util.Map[String, Object].
-function scalaLit(type: any, placeholder: string = 'example'): string {
-  const k = canonScalarKey(type)
-  if ('INTEGER' === k) return '1L'
-  if ('NUMBER' === k) return '1.0'
-  if ('BOOLEAN' === k) return 'true'
-  if ('ARRAY' === k) return 'java.util.List.of()'
-  if ('OBJECT' === k) return 'java.util.Map.of()'
-  return `"${placeholder}"`
-}
+import { scalaVarName, scalaPackage, scalaListMatch, scalaLit } from './utility_scala'
 
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
@@ -35,9 +21,12 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
+  const shown = null != exampleEntity &&
+    ['list', 'load'].some((op: string) => Object.keys(exampleEntity.op || {}).includes(op))
+
   Content(`\`\`\`scala
 import ${scalaPackage(model)}.core.${SDK}
-
+${shown ? `import ${scalaPackage(model)}.core.SdkEntity\n` : ''}
 `)
 
   if (authActive) {
@@ -61,9 +50,9 @@ val client = new ${SDK}(options)
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eNameLower}s (returns Object, an aggregate list; raises on error)
-val ${eVar}List = client.${accessor}(null).list(null, null)
-println(${eVar}List)
+      Content(`// List all ${eNameLower}s (a list of entities, one per record; raises on error)
+val ${eVar}List = client.${accessor}(null).list(${scalaListMatch(exampleEntity)}, null).asInstanceOf[java.util.List[SdkEntity]]
+${eVar}List.forEach(${eVar}Item => println(${eVar}Item.data()))
 `)
     }
 
@@ -76,14 +65,14 @@ println(${eVar}List)
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       const loadArg = 0 < loadItems.length
-        ? `java.util.Map.of(${loadItems.map((it: any) =>
+        ? javaMapOf(loadItems.map((it: any) =>
           `"${it.name}", ${scalaLit(it.type,
-            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')})`
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`), 'java.util.')
         : 'null'
       Content(`
-// Load a specific ${eNameLower} (returns the record, raises on error)
-val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
-println(${eVar})
+// Load a specific ${eNameLower} (returns the entity, raises on error)
+val ${eVar} = client.${accessor}(null).load(${loadArg}, null).asInstanceOf[SdkEntity]
+println(${eVar}.data())
 `)
     }
   }

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

@@ -1,24 +1,12 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems, javaMapOf } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { scalaVarName } from './utility_scala'
-
-
-// A type-correct Scala literal for a field's canonical type.
-function scalaLit(type: any): string {
-  const k = canonScalarKey(type)
-  if ('INTEGER' === k) return '1L'
-  if ('NUMBER' === k) return '1.0'
-  if ('BOOLEAN' === k) return 'true'
-  if ('ARRAY' === k) return 'java.util.List.of()'
-  if ('OBJECT' === k) return 'java.util.Map.of()'
-  return '"example"'
-}
+import { scalaVarName, scalaLit } from './utility_scala'
 
 
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
@@ -40,29 +28,33 @@ val client = ${SDK}.testSDK(null, null)
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'null'
-    if (isMatchOp) {
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
       // Every REQUIRED match key (id first) — the same shape that generates
       // the op's request type, so the block stays honest.
-      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
-        ? `java.util.Map.of(${items.map((it: any) =>
-          `"${it.name}", ${it.name === idF ? '"test01"' : scalaLit(it.type)}`).join(', ')})`
+        ? javaMapOf(items.map((it: any) =>
+          `${JSON.stringify(it.name)}, ${isMatchOp && it.name === idF ? '"test01"' : scalaLit(it.type)}`), 'java.util.')
         : '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)
       const chosen = required.length ? required : items.slice(0, 3)
-      arg = `java.util.Map.of(${chosen.map((it: any) =>
-        `"${it.name}", ${scalaLit(it.type)}`).join(', ')})`
+      arg = javaMapOf(chosen.map((it: any) =>
+        `${JSON.stringify(it.name)}, ${scalaLit(it.type)}`), 'java.util.')
     }
-    const eVar = scalaVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
+    const eVar = scalaVarName(exampleEntity.name)
     const accessor = scalaVarName(exampleEntity.name)
-    Content(`val ${eVar} = client.${accessor}(null).${primaryOp}(${arg}, null)
-println(${eVar})
+    Content('list' === primaryOp
+      ? `val ${eVar}List = client.${accessor}(null).list(${arg}, null).asInstanceOf[java.util.List[SdkEntity]]
+${eVar}List.forEach(${eVar}Item => println(${eVar}Item.data()))
+`
+      : `val ${eVar} = client.${accessor}(null).${primaryOp}(${arg}, null).asInstanceOf[SdkEntity]
+println(${eVar}.data())
 `)
   }
 

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)

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

@@ -1,4 +1,4 @@
-import { flowSteps } from '@voxgig/sdkgen'
+import { flowSteps, opReachable, invalidRequest } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -86,18 +86,21 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
 import java.util.{ArrayList, LinkedHashMap, List => JList, Map => JMap}
 
-import ${scalapackage}.core.{Helpers, SdkEntity, ${SDK}}
+import ${scalapackage}.core.{Config, Context, Helpers, SdkEntity, SdkError, ${SDK}}
+import ${scalapackage}.feature.BaseFeature
 import ${scalapackage}.utility.struct.Struct
 
 object ${EntityName}EntityTest {
 
+  import SdkTestSupport.{B, I, jl, om}
+${failureTests(SDK, entity, accessor)}
   def run(rep: SdkTestReport): Unit = {
     rep.scope("${ENTLOWER}.instance") {
       val testsdk = ${SDK}.testSDK()
       val ent = testsdk.${accessor}(null)
       rep.check("${ENTLOWER}.instance", ent != null, "expected non-null ${ENTLOWER} entity")
     }
-
+${failureScopes(SDK, entity, accessor)}
     rep.scope("${ENTLOWER}.basic") {
       val entityData = Helpers.toMapAny(SdkTestSupport.readJson(
           "../.sdk/test/entity/${ENTLOWER}/${EntityName}TestData.json"))
@@ -413,6 +416,113 @@ const GENERATE_OP: Record<string, OpGen> = {
 }
 
 
+// A failed operation throws from a stream as it does from the operation: a
+// transport failure, and a hook that rejects the call. A throwing hook fires
+// PreUnexpected, under throw false too. The caller's ctrl stays its own. An
+// invalid request fails with validate's own error, before it is sent.
+function failureTests(SDK: string, entity: ModelEntity, accessor: string): string {
+  const hasList = opReachable((entity.op as any)?.list, [])
+  if (!hasList && null == invalidRequest(entity)) {
+    return ''
+  }
+  return `
+  private def hasFeature(name: String): Boolean = {
+    val fm = Helpers.toMapAny(Config.sharedConfig().get("feature"))
+    fm != null && fm.get(name) != null
+  }
+${hasList ? `
+  final class FailHook extends BaseFeature("failhook", "0.0.1", true) {
+    var unexpected = 0
+    override def preSpec(ctx: Context): Unit = throw new RuntimeException("${entity.name} hook failed")
+    override def preUnexpected(ctx: Context): Unit = unexpected += 1
+  }
+` : ''}`
+}
+
+
+function failureScopes(SDK: string, entity: ModelEntity, accessor: string): string {
+  const name = entity.name
+  let out = ''
+
+  if (opReachable((entity.op as any)?.list, [])) {
+    out += `
+    rep.scope("${name}.stream.error") {
+      val offline = om("net" -> om("offline" -> B(true)))
+      val err = try {
+        ${SDK}.testSDK(offline, null).${accessor}(null).stream("list", null, null).toList
+        null
+      } catch { case e: RuntimeException => e }
+      rep.check("${name}.stream.error", err != null && String.valueOf(err.getMessage).contains("offline"),
+        "expected the transport failure to raise from the stream, got " + err)
+
+      ${SDK}.testSDK(offline, null).${accessor}(null)
+        .stream("list", null, om("ctrl" -> om("throw" -> B(false)))).toList
+
+      if (hasFeature("rbac")) {
+        val denied = ${SDK}.testSDK(null,
+          om("feature" -> om("rbac" -> om("active" -> B(true), "deny" -> B(true)))))
+        val denyerr = try {
+          denied.${accessor}(null).stream("list", null, null).toList
+          null
+        } catch { case e: SdkError => e }
+        rep.check("${name}.stream.denied", denyerr != null && "rbac_denied" == denyerr.code,
+          "expected the rbac denial to raise from the stream, got " + denyerr)
+      }
+    }
+
+    rep.scope("${name}.stream.ctrl") {
+      val explain = new LinkedHashMap[String, Object]()
+      val ctrl = om("explain" -> explain)
+      ${SDK}.testSDK().${accessor}(null).stream("list", null, om("ctrl" -> ctrl)).toList
+      rep.check("${name}.stream.ctrl", 1 == ctrl.size() && (explain eq ctrl.get("explain")),
+        "the stream changed the caller's ctrl")
+      rep.check("${name}.stream.explain", !explain.isEmpty(), "the caller's explain record was not filled")
+    }
+
+    rep.scope("${name}.unexpected") {
+      val hook = new FailHook()
+      val client = new ${SDK}(om("feature" -> om("test" -> om("active" -> B(true))), "extend" -> jl(hook)))
+      val err = try {
+        client.${accessor}(null).list(null, null)
+        null
+      } catch { case e: RuntimeException => e }
+      rep.check("${name}.unexpected.raise", err != null && String.valueOf(err.getMessage).contains("hook failed"),
+        "expected the hook's failure, got " + err)
+      rep.check("${name}.unexpected.fired", hook.unexpected > 0, "PreUnexpected did not fire")
+
+      val fired = hook.unexpected
+      client.${accessor}(null).list(null, om("throw" -> B(false)))
+      rep.check("${name}.unexpected.nothrow", hook.unexpected > fired,
+        "PreUnexpected did not fire under throw false")
+    }
+`
+  }
+
+  const bad = invalidRequest(entity)
+  if (null != bad) {
+    const args = Object.entries(bad.args)
+      .map(([k, v]) => JSON.stringify(k) + ' -> ' +
+        ('number' === typeof v ? 'I(' + v + ')' : 'boolean' === typeof v ? 'B(' + v + ')' : JSON.stringify(v)))
+      .join(', ')
+    out += `
+    rep.scope("${name}.validate") {
+      if (hasFeature("validate")) {
+        val client = ${SDK}.testSDK(null, om("feature" -> om("validate" -> om("active" -> B(true)))))
+        val err = try {
+          client.${accessor}(null).${bad.op}(om(${args}), null)
+          null
+        } catch { case e: SdkError => e }
+        rep.check("${name}.validate", err != null && "validate_failed" == err.code,
+          "expected validate_failed, got " + err)
+      }
+    }
+`
+  }
+
+  return out
+}
+
+
 export {
   TestEntity
 }

package/project/.sdk/src/cmp/scala/fragment/Entity.fragment.scala

@@ -20,5 +20,7 @@ class EntyClass(client0: SdkClient, entopts0: JMap[String, Object]) extends Enti
 
 // #UpdateOp
 
+// #PatchOp
+
 // #RemoveOp
 }

package/project/.sdk/src/cmp/scala/fragment/EntityBase.fragment.scala

@@ -164,8 +164,10 @@ abstract class EntityBase(name0: String, client0: SdkClient, entopts0: JMap[Stri
 
     val signal = opts.get("signal")
 
-    var ctrl = Helpers.toMapAny(opts.get("ctrl"))
-    if (ctrl == null) ctrl = new LinkedHashMap[String, Object]()
+    // A copy: the caller's ctrl gains no key, and explain stays its own record.
+    val ctrl = new LinkedHashMap[String, Object]()
+    val callerCtrl = Helpers.toMapAny(opts.get("ctrl"))
+    if (callerCtrl != null) ctrl.putAll(callerCtrl)
     ctrl.put("stream", opts)
 
     val ctxmap = new LinkedHashMap[String, Object]()

package/project/.sdk/src/cmp/scala/fragment/EntityPatchOp.fragment.scala

@@ -0,0 +1,33 @@
+package SCALAPACKAGE.entity
+
+import java.util.{LinkedHashMap, Map => JMap}
+import SCALAPACKAGE.core.{Helpers, SdkClient}
+import SCALAPACKAGE.utility.struct.Struct
+
+abstract class EntityPatchOpFragment(client: SdkClient, entopts: JMap[String, Object])
+    extends EntityBase("entityname", client, entopts) {
+
+// EJECT-START
+
+  override def patch(reqdata: JMap[String, Object], ctrl: JMap[String, Object]): Object = {
+    val ctxmap = new LinkedHashMap[String, Object]()
+    ctxmap.put("opname", "patch")
+    ctxmap.put("ctrl", ctrl)
+    ctxmap.put("match", this.matchState)
+    ctxmap.put("data", this.dataState)
+    ctxmap.put("reqdata", reqdata)
+    val ctx = this.utility.makeContext(ctxmap, this.entctx)
+
+    runOp(ctx, () => {
+      if (ctx.result != null) {
+        if (ctx.result.resmatch != null) this.matchState = ctx.result.resmatch
+        if (ctx.result.resdata != null) {
+          val d = Helpers.toMapAny(Struct.clone(ctx.result.resdata))
+          this.dataState = if (d == null) new LinkedHashMap[String, Object]() else d
+        }
+      }
+    })
+  }
+
+// EJECT-END
+}