@voxgig/sdkgen 4.34.0 → 4.34.2

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

@@ -20,13 +20,14 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
-    load: '| `Load` | `(reqmatch, ctrl) -> object?` | Load a single entity by match criteria. Raises on error. |',
-    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. |',
-    remove: '| `Remove` | `(reqmatch, ctrl) -> object?` | Remove an entity. Raises on error. |',
+    load: '| `Load` | `(reqmatch, ctrl) -> object?` | Load a single entity by match criteria, and return it. Raises on error. |',
+    list: '| `List` | `(reqmatch, ctrl) -> object?` | List entities matching the criteria, one per record. Raises on error. |',
+    create: '| `Create` | `(reqdata, ctrl) -> object?` | Create a new entity, and return it. Raises on error. |',
+    update: '| `Update` | `(reqdata, ctrl) -> object?` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `Patch` | `(reqdata, ctrl) -> object?` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `Remove` | `(reqmatch, ctrl) -> object?` | Remove an entity, and return it marked as deleted. 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)
@@ -91,9 +92,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (a \`Dictionary\` for
-single-entity ops, an aggregate list for \`List\`) as \`object?\` and raise on
-error. Wrap calls in \`try\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`List\` a list of entities, one per
+record, as \`object?\`; an entity is an \`IEntity\`, whose \`Data()\` reads its
+record. They raise on error, so wrap calls in \`try\`/\`catch\` to handle
+failures.
 
 The \`Direct()\` escape hatch never raises — it returns a result
 \`Dictionary<string, object?>\` you branch on via \`result["ok"]\`:

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

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { csVarName } from './utility_csharp'
+import { csVarName, csListMatch } from './utility_csharp'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -37,6 +37,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
 \`\`\`csharp
 using ${model.const.Name}Sdk;
+using Voxgig.Struct;
 
 var client = ${ctor};
 \`\`\`
@@ -57,6 +58,7 @@ var client = ${ctor};
     // A type-correct C# literal for a param.
     const csLit = (type: any, placeholder: string = 'example'): string => {
       const k = canonScalarKey(type)
+      if ('NULL' === k) return 'null'
       if ('INTEGER' === k) return '1L'
       if ('NUMBER' === k) return '1.0'
       if ('BOOLEAN' === k) return 'true'
@@ -68,14 +70,17 @@ var client = ${ctor};
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`List(null)\` returns an aggregate list of records (as \`object?\`) and raises
-on error.
+\`List(null)\` returns a list of entities, one per record (as \`object?\`), and
+raises on error; an entity's \`Data()\` reads its record.
 
 \`\`\`csharp
 try
 {
-    var ${eVar}List = client.${eName}().List(null);
-    Console.WriteLine(${eVar}List);
+    var ${eVar}List = (List<object?>)client.${eName}().List(${csListMatch(exampleEntity)})!;
+    foreach (var ${eVar}Item in ${eVar}List)
+    {
+        Console.WriteLine(StructUtils.Jsonify(((IEntity)${eVar}Item!).Data()));
+    }
 }
 catch (Exception err)
 {
@@ -108,13 +113,14 @@ catch (Exception err)
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`Load()\` returns the bare record (as \`object?\`) and raises on error.
+\`Load()\` returns the entity (as \`object?\`) and raises on error; an entity's
+\`Data()\` reads its record.
 
 \`\`\`csharp
 try
 {
-    var ${neVar} = client.${neName}().Load(new Dictionary<string, object?> { ${neMatch.join(', ')} });
-    Console.WriteLine(${neVar});
+    var ${neVar} = (IEntity)client.${neName}().Load(new Dictionary<string, object?> { ${neMatch.join(', ')} })!;
+    Console.WriteLine(StructUtils.Jsonify(${neVar}.Data()));
 }
 catch (Exception err)
 {
@@ -138,13 +144,14 @@ catch (Exception err)
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`Load()\` returns the bare record (as \`object?\`) and raises on error.
+\`Load()\` returns the entity (as \`object?\`) and raises on error; an entity's
+\`Data()\` reads its record.
 
 \`\`\`csharp
 try
 {
-    var ${eVar} = client.${eName}().Load(${loadArg});
-    Console.WriteLine(${eVar});
+    var ${eVar} = (IEntity)client.${eName}().Load(${loadArg})!;
+    Console.WriteLine(StructUtils.Jsonify(${eVar}.Data()));
 }
 catch (Exception err)
 {
@@ -174,13 +181,14 @@ catch (Exception err)
       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
 
 \`\`\`csharp
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record (as object?)
+        Content(`// Create — returns the created entity (as object?)
 var created = client.${eName}().Create(new Dictionary<string, object?> { ${examplePairs('create').join(', ')} });
 
 `)
@@ -191,6 +199,14 @@ var created = client.${eName}().Create(new Dictionary<string, object?> { ${examp
         Content(`// Update — supply the id in the match/data
 client.${eName}().Update(new Dictionary<string, object?> { ${updatePairs.join(', ')} });
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`["${idF}"] = ${csLit(idParamType('patch'), 'example_id')}`] : [])
+          .concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+client.${eName}().Patch(new Dictionary<string, object?> { ${patchPairs.join(', ')} });
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/csharp/ReadmeRef_csharp.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 {
@@ -7,7 +7,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { csVarName } from './utility_csharp'
+import { csVarName, csListMatch } from './utility_csharp'
 
 
 // Type names come from the shared canonToType 'csharp' column (single source of truth).
@@ -15,6 +15,7 @@ import { csVarName } from './utility_csharp'
 // A type-correct C# literal for a field's canonical type.
 function csLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'
@@ -27,28 +28,33 @@ function csLit(type: any, placeholder: string = 'example'): string {
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'Load(reqmatch, ctrl = null) -> 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 = null) -> object?',
-    returns: 'an aggregate list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `List(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)` to list all records. Returns a list of entities, one per record, and raises on error.',
   },
   create: {
     sig: 'Create(reqdata, ctrl = null) -> 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 = null) -> 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 = null) -> 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 = null) -> 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.',
   },
 }
 
@@ -78,6 +84,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
 
     Content(`\`\`\`csharp
 using ${model.const.Name}Sdk;
+using Voxgig.Struct;
 
 var client = new ${model.const.Name}SDK(options);
 \`\`\`
@@ -217,7 +224,7 @@ var ${eVar} = client.${ent.Name}();
         // 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 +265,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)
@@ -276,8 +287,11 @@ var result = client.${ent.Name}().${opname.charAt(0).toUpperCase() + opname.slic
           }
           else if ('list' === opname) {
             Content(`\`\`\`csharp
-var results = client.${ent.Name}().List(null);
-Console.WriteLine(results);
+var results = (List<object?>)client.${ent.Name}().List(${csListMatch(ent)})!;
+foreach (var item in results)
+{
+    Console.WriteLine(StructUtils.Jsonify(((IEntity)item!).Data()));
+}
 \`\`\`
 
 `)
@@ -298,8 +312,8 @@ var result = client.${ent.Name}().Create(new Dictionary<string, object?>
 
 `)
           }
-          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))
@@ -307,14 +321,22 @@ var result = client.${ent.Name}().Create(new Dictionary<string, object?>
               `    ["${it.name}"] = ${csLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`csharp
-var result = client.${ent.Name}().Update(new Dictionary<string, object?>
+var result = client.${ent.Name}().${'patch' === opname ? 'Patch' : 'Update'}(new Dictionary<string, object?>
 {
-${updateLines}    // Fields to update
+${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 `byte[]`, a `string` or a `Stream`',
+              once: 'a `Stream`',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

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

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { csVarName } from './utility_csharp'
+import { csVarName, csListMatch } from './utility_csharp'
 
 
 // A type-correct C# literal for a param: numeric/boolean/array/object params
@@ -15,6 +15,7 @@ import { csVarName } from './utility_csharp'
 // loose object model means all values live in Dictionary<string, object?>.
 function csLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'
@@ -36,9 +37,12 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
     ? `new ${model.const.Name}SDK(new Dictionary<string, object?>\n{\n    ["apikey"] = Environment.GetEnvironmentVariable("${envName(model)}_APIKEY"),\n})`
     : `new ${model.const.Name}SDK()`
 
+  const shown = null != exampleEntity &&
+    ['list', 'load'].some((op: string) => Object.keys(exampleEntity.op || {}).includes(op))
+
   Content(`\`\`\`csharp
 using ${model.const.Name}Sdk;
-
+${shown ? 'using Voxgig.Struct;\n' : ''}
 var client = ${ctor};
 
 `)
@@ -52,9 +56,12 @@ var client = ${ctor};
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns object?, an aggregate list; raises on error)
-var ${eVar}List = client.${eName}().List(null);
-Console.WriteLine(${eVar}List);
+      Content(`// List all ${eName.toLowerCase()}s (a list of entities, one per record, as object?; raises on error)
+var ${eVar}List = (List<object?>)client.${eName}().List(${csListMatch(exampleEntity)})!;
+foreach (var ${eVar}Item in ${eVar}List)
+{
+    Console.WriteLine(StructUtils.Jsonify(((IEntity)${eVar}Item!).Data()));
+}
 `)
     }
 
@@ -72,9 +79,9 @@ Console.WriteLine(${eVar}List);
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(',')} }`
         : 'null'
       Content(`
-// Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
-var ${eVar} = client.${eName}().Load(${loadArg});
-Console.WriteLine(${eVar});
+// Load a specific ${eName.toLowerCase()} (returns the entity, raises on error)
+var ${eVar} = (IEntity)client.${eName}().Load(${loadArg})!;
+Console.WriteLine(StructUtils.Jsonify(${eVar}.Data()));
 `)
     }
   }

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,12 +7,13 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { csVarName } from './utility_csharp'
+import { csVarName, csStringLiteral } from './utility_csharp'
 
 
 // A type-correct C# literal for a field's canonical type.
 function csLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'
@@ -41,28 +42,35 @@ var client = ${model.const.Name}SDK.TestSDK(null, null);
     const opMethod = primaryOp.charAt(0).toUpperCase() + primaryOp.slice(1)
     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
         ? `new Dictionary<string, object?> {${items.map((it: any) =>
-          ` ["${it.name}"] = ${it.name === idF ? '"test01"' : csLit(it.type)}`).join(',')} }`
+          ` [${csStringLiteral(it.name)}] = ${isMatchOp && it.name === idF ? '"test01"' : csLit(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)
       const chosen = required.length ? required : items.slice(0, 3)
       arg = `new Dictionary<string, object?> {${chosen.map((it: any) =>
-        ` ["${it.name}"] = ${csLit(it.type)}`).join(',')} }`
+        ` [${csStringLiteral(it.name)}] = ${csLit(it.type)}`).join(',')} }`
     }
-    const eVar = csVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
-    Content(`var ${eVar} = client.${eName}().${opMethod}(${arg});
-Console.WriteLine(${eVar});
+    const eVar = csVarName(exampleEntity.name)
+    Content('list' === primaryOp
+      ? `var ${eVar}List = (List<object?>)client.${eName}().List(${arg})!;
+foreach (var ${eVar}Item in ${eVar}List)
+{
+    Console.WriteLine(StructUtils.Jsonify(((IEntity)${eVar}Item!).Data()));
+}
+`
+      : `var ${eVar} = (IEntity)client.${eName}().${opMethod}(${arg})!;
+Console.WriteLine(StructUtils.Jsonify(${eVar}.Data()));
 `)
   }
 

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

@@ -8,6 +8,7 @@ import {
   isHttpBasicAuth,
   resolveAuthIn,
   resolveAuthName,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -27,6 +28,10 @@ const TestClean = cmp(function TestClean(props: any) {
     basic: isHttpBasicAuth(model),
   }
 
+  // CostRecord is declared by the cost feature's source, which ships only
+  // when the model selects the feature.
+  const cost = null != targetFeatures(model, target).cost
+
   // Same order the ts sweep tries: list, then load, then the rest.
   const rank: Record<string, number> = { list: 0, load: 1 }
   const candidates = each(entityCollection(model))
@@ -39,7 +44,7 @@ const TestClean = cmp(function TestClean(props: any) {
     }))
     .filter((c: any) => 0 < c.ops.length)
 
-  File({ name: 'CleanTest.' + target.ext }, () => Content(render(model.const.Name, auth, candidates)))
+  File({ name: 'CleanTest.' + target.ext }, () => Content(render(model.const.Name, auth, candidates, cost)))
 })
 
 
@@ -47,6 +52,7 @@ function render(
   Name: string,
   auth: { suppressed: boolean, where: string, name: string, basic: boolean },
   candidates: { name: string, Name: string, ops: string[] }[],
+  cost: boolean,
 ): string {
   const candidateLines = candidates.map((c) =>
     `        new Candidate("${c.name}", sdk => sdk.${c.Name}(null), new[] { ${c.ops.map((o) => `"${o}"`).join(', ')} }),`)
@@ -370,8 +376,34 @@ public class CleanTest
         }),
     };
 
+    // Offline, as every generated suite is: the test OPTION resolves a
+    // required server variable to test-<name>, and installs no transport.
+    private static Dictionary<string, object?> Offline(Dictionary<string, object?> opts)
+    {
+        var copy = new Dictionary<string, object?>(opts);
+        copy["test"] = new Dictionary<string, object?> { ["active"] = true };
+        return copy;
+    }
+
+    // A client the sweep cannot build leaves nothing swept: a harness error,
+    // not a leak.
+    private static ${Name}SDK Construct(Dictionary<string, object?> opts)
+    {
+        try
+        {
+            return new ${Name}SDK(Offline(opts));
+        }
+        catch (Exception e)
+        {
+            throw new InvalidOperationException(
+                "clean harness: the client could not be constructed, so nothing was swept: " +
+                e.Message, e);
+        }
+    }
+
     private static ${Name}SDK MakeSdk(Scenario scenario, List<Sink> sinks,
-        Dictionary<string, object?>? cleanopts = null, BaseFeature? extra = null)
+        Dictionary<string, object?>? cleanopts = null, BaseFeature? extra = null,
+        Dictionary<string, object?>? auth = null)
     {
         Action<Dictionary<string, object?>> Capture(string name) =>
             rec => sinks.AddRange(FormsOf(name, rec));
@@ -407,7 +439,7 @@ public class CleanTest
                 ["active"] = true, ["exporter"] = Capture("telemetry"),
             };
         }
-        if (Fh.HasFeature("cost"))
+${cost ? `        if (Fh.HasFeature("cost"))
         {
             feature["cost"] = new Dictionary<string, object?>
             {
@@ -415,7 +447,7 @@ public class CleanTest
                 ["sink"] = (Action<CostRecord>)(rec => sinks.AddRange(FormsOf("cost", rec))),
             };
         }
-        if (Fh.HasFeature("metrics"))
+` : ''}        if (Fh.HasFeature("metrics"))
         {
             feature["metrics"] = new Dictionary<string, object?> { ["active"] = true };
         }
@@ -439,7 +471,7 @@ public class CleanTest
             extend.Add(extra);
         }
 
-        return new ${Name}SDK(new Dictionary<string, object?>
+        var opts = new Dictionary<string, object?>
         {
             ["apikey"] = CanaryApikey,
             ["secret"] = CanarySecret,
@@ -448,7 +480,12 @@ public class CleanTest
             ["feature"] = feature,
             ["extend"] = extend,
             ["utility"] = new Dictionary<string, object?> { ["fetcher"] = fetcher },
-        });
+        };
+        if (null != auth)
+        {
+            opts["auth"] = auth;
+        }
+        return Construct(opts);
     }
 
     // Emitted from the model: every active entity with the operations it
@@ -468,6 +505,7 @@ ${candidateLines}
             "load" => ent.Load(args, ctrl),
             "create" => ent.Create(args, ctrl),
             "update" => ent.Update(args, ctrl),
+            "patch" => ent.Patch(args, ctrl),
             "remove" => ent.Remove(args, ctrl),
             _ => throw new InvalidOperationException("unknown operation: " + op),
         };
@@ -499,7 +537,7 @@ ${candidateLines}
     {
         var fetcher = (Context _ctx, string _url, Dictionary<string, object?> _def) =>
             (object?)Response(200, new Dictionary<string, object?> { ["id"] = "i1" });
-        var plain = new ${Name}SDK(new Dictionary<string, object?>
+        var plain = Construct(new Dictionary<string, object?>
         {
             ["apikey"] = CanaryApikey,
             ["utility"] = new Dictionary<string, object?> { ["fetcher"] = fetcher },
@@ -532,11 +570,12 @@ ${candidateLines}
     {
         // A caller may keep the record it passed rather than read ctrl's entry.
         var held = ctrl.GetValueOrDefault("explain");
+        var entity = target.Candidate.Accessor(sdk);
         object? out_ = null;
         Exception? err = null;
         try
         {
-            out_ = Invoke(target.Candidate.Accessor(sdk), target.Op, target.Match, ctrl);
+            out_ = Invoke(entity, target.Op, target.Match, ctrl);
         }
         catch (Exception e)
         {
@@ -544,6 +583,8 @@ ${candidateLines}
         }
         if (null != err) sinks.AddRange(FormsOf("error", err));
         if (null != out_) sinks.AddRange(FormsOf("result", out_));
+        // Raw, as a caller copying the match into another query reads it.
+        sinks.AddRange(FormsOf("match", entity.Match()));
         if (ctrl.TryGetValue("explain", out var explain) && null != explain)
         {
             sinks.AddRange(FormsOf("explain", explain));
@@ -608,16 +649,21 @@ ${candidateLines}
             }
         }
 
+        // A name given at run time replaces the declared one: the match leaves
+        // out whichever name PrepareAuth placed.
+        Drive(MakeSdk(Scenarios[0], sinks, auth: new Dictionary<string, object?> { ["name"] = "zzcred" }),
+            target, new Dictionary<string, object?>(), sinks);
+
         // A credential mistyped as a map is rejected by validation, whose
         // message quotes the value it rejected.
         Exception? rejected = null;
         try
         {
-            new ${Name}SDK(new Dictionary<string, object?>
+            new ${Name}SDK(Offline(new Dictionary<string, object?>
             {
                 ["apikey"] = new Dictionary<string, object?> { ["value"] = CanaryApikey },
                 ["clean"] = new Dictionary<string, object?> { ["values"] = CanaryValue },
-            });
+            }));
         }
         catch (Exception e)
         {
@@ -776,11 +822,12 @@ ${candidateLines}
 
     // 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.
+    // seeded records keyed by entity name and id, is not read at all, and nor
+    // are rbac's rules, keyed by entity and operation names.
     [Fact]
     public void AFeatureNameDoesNotMakeItsSettingsSecret()
     {
-        var sdk = new ${Name}SDK(new Dictionary<string, object?>
+        var sdk = Construct(new Dictionary<string, object?>
         {
             ["apikey"] = CanaryApikey,
             ["feature"] = new Dictionary<string, object?>
@@ -793,6 +840,11 @@ ${candidateLines}
                 {
                     ["active"] = false, ["apitoken"] = "FEATTOKEN-z9y8x7w6",
                 },
+                ["rbac"] = new Dictionary<string, object?>
+                {
+                    ["active"] = false,
+                    ["rules"] = new Dictionary<string, object?> { ["zztoken.load"] = "PLAINRULE-k7j5h3g1" },
+                },
                 ["test"] = new Dictionary<string, object?>
                 {
                     ["active"] = false,
@@ -819,12 +871,13 @@ ${candidateLines}
         Assert.Equal("token " + Mask, Cleaned("token FEATTOKEN-z9y8x7w6"));
         Assert.Equal("record PLAINRECORD-t5r3e1w9", Cleaned("record PLAINRECORD-t5r3e1w9"));
         Assert.Equal("alias PLAINALIAS-m2n4b6v8", Cleaned("alias PLAINALIAS-m2n4b6v8"));
+        Assert.Equal("rule PLAINRULE-k7j5h3g1", Cleaned("rule PLAINRULE-k7j5h3g1"));
     }
 
     [Fact]
     public void TheGeneratedConfigsOwnCleanBlockIsHonoured()
     {
-        var utility = new ${Name}SDK(new Dictionary<string, object?>()).GetUtility();
+        var utility = Construct(new Dictionary<string, object?>()).GetUtility();
         var config = new Dictionary<string, object?>
         {
             ["options"] = new Dictionary<string, object?>
@@ -862,7 +915,7 @@ ${candidateLines}
     [Fact]
     public void WithNoCleanBlockTheSchemaDefaultsApply()
     {
-        var utility = new ${Name}SDK(new Dictionary<string, object?>()).GetUtility();
+        var utility = Construct(new Dictionary<string, object?>()).GetUtility();
         var ctx = utility.MakeContext(new Dictionary<string, object?>
         {
             ["utility"] = utility,