@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/cpp/ReadmeIntro_cpp.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 { cppVarName } from './utility_cpp'
 
 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
@@ -37,7 +37,7 @@ entity-oriented client following idiomatic modern C++ (C++17) conventions.
   // 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/cpp/ReadmeModel_cpp.ts

@@ -22,13 +22,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) -> Value` | Load a single entity by match criteria. Throws on error. |',
-    list: '| `list` | `(reqmatch, ctrl) -> Value` | List entities matching the criteria (a Value list). Throws on error. |',
-    create: '| `create` | `(reqdata, ctrl) -> Value` | Create a new entity. Throws on error. |',
-    update: '| `update` | `(reqdata, ctrl) -> Value` | Update an existing entity. Throws on error. |',
-    remove: '| `remove` | `(reqmatch, ctrl) -> Value` | Remove an entity. Throws on error. |',
+    load: '| `load` | `(reqmatch, ctrl) -> SdkEntityPtr` | Load a single entity by match criteria. Throws on error. |',
+    list: '| `list` | `(reqmatch, ctrl) -> std::vector<SdkEntityPtr>` | List entities matching the criteria, one per record. Throws on error. |',
+    create: '| `create` | `(reqdata, ctrl) -> SdkEntityPtr` | Create a new entity. Throws on error. |',
+    update: '| `update` | `(reqdata, ctrl) -> SdkEntityPtr` | Update an existing entity. Throws on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> SdkEntityPtr` | Change part of an existing entity. Throws on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> SdkEntityPtr` | Remove an entity, which is returned marked as deleted. Throws 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)
@@ -97,9 +98,9 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (a map \`Value\` for
-single-entity ops, a list \`Value\` for \`list\`) and throw
-\`sdk::SdkErrorPtr\` on error. Wrap calls in \`try\`/\`catch\` to handle
+Entity operations return the entity, and \`list\` a \`std::vector\` of
+entities, one per record; \`data()\` reads an entity's record. They throw
+\`sdk::SdkErrorPtr\` on error, so wrap calls in \`try\`/\`catch\` to handle
 failures.
 
 The \`direct()\` escape hatch never throws — it returns a result \`Value\`

package/project/.sdk/src/cmp/cpp/ReadmeQuick_cpp.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppListMatch } from './utility_cpp'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -57,6 +57,7 @@ ${ctor}
   // params render a typed sdk::Value; strings render the quoted placeholder.
   const cppLit = (type: any, placeholder: string = 'example'): string => {
     const k = canonScalarKey(type)
+    if ('NULL' === k) return 'Value(nullptr)'
     if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
     if ('BOOLEAN' === k) return 'Value(true)'
     if ('ARRAY' === k) return 'vlist()'
@@ -79,14 +80,14 @@ ${ctor}
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` returns an \`sdk::Value\` list and throws \`sdk::SdkErrorPtr\`
-on error — iterate it directly.
+\`list()\` returns a \`std::vector\` of entities, one per record, and throws
+\`sdk::SdkErrorPtr\` on error; \`data()\` reads an entity's record.
 
 \`\`\`cpp
 try {
-  Value ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
-  for (const auto& ${eVar} : *${eVar}s.as_list()) {
-    std::cout << Struct::jsonify(${eVar}) << std::endl;
+  std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(${cppListMatch(exampleEntity)}, Value::undef());
+  for (const auto& ${eVar} : ${eVar}s) {
+    std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
   }
 } catch (const SdkErrorPtr& err) {
   std::cerr << "list failed: " << err->msg << std::endl;
@@ -120,12 +121,12 @@ try {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record and throws on error.
+\`load()\` returns the entity and throws on error; \`data()\` reads its record.
 
 \`\`\`cpp
 try {
-  Value ${neVar} = client->${neAcc}()->load(vmap({${neMatch.join(', ')}}), Value::undef());
-  std::cout << Struct::jsonify(${neVar}) << std::endl;
+  SdkEntityPtr ${neVar} = client->${neAcc}()->load(vmap({${neMatch.join(', ')}}), Value::undef());
+  std::cout << Struct::jsonify(${neVar}->data()) << std::endl;
 } catch (const SdkErrorPtr& err) {
   std::cerr << "load failed: " << err->msg << std::endl;
 }
@@ -146,12 +147,12 @@ try {
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record and throws on error.
+\`load()\` returns the entity and throws on error; \`data()\` reads its record.
 
 \`\`\`cpp
 try {
-  Value ${eVar} = client->${acc}()->load(${loadArg}, Value::undef());
-  std::cout << Struct::jsonify(${eVar}) << std::endl;
+  SdkEntityPtr ${eVar} = client->${acc}()->load(${loadArg}, Value::undef());
+  std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
 } catch (const SdkErrorPtr& err) {
   std::cerr << "load failed: " << err->msg << std::endl;
 }
@@ -172,25 +173,26 @@ try {
       return chosen.map((it: any) => `{"${it.name}", ${cppLit(it.type, 'example_' + it.name)}}`)
     }
 
-    // The id VALUE for an update/remove match: read off the returned `created`
-    // record only when its data type carries the id AND a create ran; otherwise
-    // a type-correct literal.
+    // The id VALUE for an update/remove match: read off the created entity's
+    // record only when its data type carries the id AND a create ran;
+    // otherwise a type-correct literal.
     const idParamType = (opname: string): any => {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `getp(created, "${dataIdF}")`
+      ? `getp(created->data(), "${dataIdF}")`
       : cppLit(idParamType(opname), 'example_id')
 
-    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
 
 \`\`\`cpp
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record.
-Value created = client->${acc}()->create(vmap({${examplePairs('create').join(', ')}}), Value::undef());
+        Content(`// Create — returns the created entity.
+SdkEntityPtr created = client->${acc}()->create(vmap({${examplePairs('create').join(', ')}}), Value::undef());
 
 `)
       }
@@ -200,6 +202,13 @@ Value created = client->${acc}()->create(vmap({${examplePairs('create').join(',
         Content(`// Update${fromCreated ? " — reuse the created record's id" : ''}
 client->${acc}()->update(vmap({${updatePairs.join(', ')}}), Value::undef());
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`{"${idF}", ${idValueFor('patch')}}`] : []).concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+client->${acc}()->patch(vmap({${patchPairs.join(', ')}}), Value::undef());
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/cpp/ReadmeRef_cpp.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 { cppVarName } from './utility_cpp'
+import { cppVarName, cppListMatch } from './utility_cpp'
 
 
 // Type names come from the shared canonToType 'cpp' column (single source of truth).
@@ -15,6 +15,7 @@ import { cppVarName } from './utility_cpp'
 // A type-correct C++ literal for a field's canonical type.
 function cppLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -25,29 +26,34 @@ function cppLit(type: any, placeholder: string = 'example'): string {
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'load(reqmatch, ctrl) -> Value',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and throws on error.',
+    sig: 'load(reqmatch, ctrl) -> SdkEntityPtr',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data()` reads, and throws on error.',
   },
   list: {
-    sig: 'list(reqmatch, ctrl) -> Value',
+    sig: 'list(reqmatch, ctrl) -> std::vector<SdkEntityPtr>',
     returns: 'a list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — pass `Value::undef()` to list all records. Returns a Value list and throws on error.',
+    desc: 'List entities matching the given criteria. The match is optional — pass `Value::undef()` to list all records. Returns one entity per record and throws on error.',
   },
   create: {
-    sig: 'create(reqdata, ctrl) -> Value',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and throws on error.',
+    sig: 'create(reqdata, ctrl) -> SdkEntityPtr',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and throws on error.',
   },
   update: {
-    sig: 'update(reqdata, ctrl) -> Value',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and throws on error.',
+    sig: 'update(reqdata, ctrl) -> SdkEntityPtr',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and throws on error.',
+  },
+  patch: {
+    sig: 'patch(reqdata, ctrl) -> SdkEntityPtr',
+    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 throws on error.',
   },
   remove: {
-    sig: 'remove(reqmatch, ctrl) -> Value',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Throws on error.',
+    sig: 'remove(reqmatch, ctrl) -> SdkEntityPtr',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and throws on error.',
   },
 }
 
@@ -214,7 +220,7 @@ auto ${acc} = client->${acc}();
         // 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
 
@@ -255,6 +261,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)
@@ -266,16 +276,17 @@ ${info.desc}
                   it.name === idF ? ent.name + '_id' : it.name)}}`).join(', ')}})`
               : 'Value::undef()'
             Content(`\`\`\`cpp
-Value result = client->${acc}()->${opname}(${arg}, Value::undef());
+SdkEntityPtr result = client->${acc}()->${opname}(${arg}, Value::undef());
+std::cout << Struct::jsonify(result->data()) << std::endl;
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`cpp
-Value results = client->${acc}()->list(Value::undef(), Value::undef());
-for (const auto& ${acc} : *results.as_list()) {
-  std::cout << Struct::jsonify(${acc}) << std::endl;
+std::vector<SdkEntityPtr> results = client->${acc}()->list(${cppListMatch(ent)}, Value::undef());
+for (const auto& ${acc} : results) {
+  std::cout << Struct::jsonify(${acc}->data()) << std::endl;
 }
 \`\`\`
 
@@ -285,7 +296,7 @@ for (const auto& ${acc} : *results.as_list()) {
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
             Content(`\`\`\`cpp
-Value result = client->${acc}()->create(vmap({
+SdkEntityPtr result = client->${acc}()->create(vmap({
 `)
             createItems.map((it: any) => {
               Content(`    {"${it.name}", ${cppLit(it.type, 'example_' + it.name)}},  // ${canonToType(it.type, target.name)}
@@ -296,8 +307,8 @@ Value result = client->${acc}()->create(vmap({
 
 `)
           }
-          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))
@@ -305,13 +316,20 @@ Value result = client->${acc}()->create(vmap({
               `    {"${it.name}", ${cppLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)}},\n`).join('')
             Content(`\`\`\`cpp
-Value result = client->${acc}()->update(vmap({
-${updateLines}    // Fields to update
+SdkEntityPtr result = client->${acc}()->${opname}(vmap({
+${updateLines}    // ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 }), Value::undef());
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a `std::string` holding the bytes',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/cpp/ReadmeTopQuick_cpp.ts

@@ -6,12 +6,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppListMatch } from './utility_cpp'
 
 
 // A type-correct C++ literal for a param.
 function cppLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -57,10 +58,10 @@ ${ctor}
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${acc}s (returns a Value list, throws on error)
-Value ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
-for (const auto& ${eVar} : *${eVar}s.as_list()) {
-  std::cout << Struct::jsonify(${eVar}) << std::endl;
+      Content(`// List all ${acc}s (one entity per record, throws on error)
+std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(${cppListMatch(exampleEntity)}, Value::undef());
+for (const auto& ${eVar} : ${eVar}s) {
+  std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
 }
 `)
     }
@@ -77,9 +78,9 @@ for (const auto& ${eVar} : *${eVar}s.as_list()) {
             it.name === idF ? 'example_id' : 'example_' + it.name)}}`).join(', ')}})`
         : 'Value::undef()'
       Content(`
-// Load a specific ${acc} (returns the record, throws on error)
-Value ${eVar} = client->${acc}()->load(${loadArg}, Value::undef());
-std::cout << Struct::jsonify(${eVar}) << std::endl;
+// Load a specific ${acc} (returns the entity, throws on error)
+SdkEntityPtr ${eVar} = client->${acc}()->load(${loadArg}, Value::undef());
+std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
 `)
     }
   }

package/project/.sdk/src/cmp/cpp/ReadmeTopTest_cpp.ts

@@ -1,17 +1,18 @@
 
-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,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppEscape } from './utility_cpp'
 
 
 // A type-correct C++ literal for a field's canonical type.
 function cppLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -37,26 +38,33 @@ auto client = ${model.const.Name}SDK::testSDK();
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'Value::undef()'
-    if (isMatchOp) {
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
+      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
         ? `vmap({${items.map((it: any) =>
-          `{"${it.name}", ${it.name === idF ? 'Value("test01")' : cppLit(it.type)}}`).join(', ')}})`
+          `{"${cppEscape(it.name)}", ${isMatchOp && it.name === idF ? 'Value("test01")' : cppLit(it.type)}}`).join(', ')}})`
         : 'Value::undef()'
-    } 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 = `vmap({${chosen.map((it: any) => `{"${it.name}", ${cppLit(it.type)}}`).join(', ')}})`
+      arg = `vmap({${chosen.map((it: any) => `{"${cppEscape(it.name)}", ${cppLit(it.type)}}`).join(', ')}})`
     }
-    const eVar = acc + ('list' === primaryOp ? 's' : '')
-    Content(`Value ${eVar} = client->${acc}()->${primaryOp}(${arg}, Value::undef());
-std::cout << Struct::jsonify(${eVar}) << std::endl;
+    if ('list' === primaryOp) {
+      Content(`for (const auto& ${acc} : client->${acc}()->list(${arg}, Value::undef())) {
+  std::cout << Struct::jsonify(${acc}->data()) << std::endl;
+}
 `)
+    }
+    else {
+      Content(`SdkEntityPtr ${acc} = client->${acc}()->${primaryOp}(${arg}, Value::undef());
+std::cout << Struct::jsonify(${acc}->data()) << std::endl;
+`)
+    }
   }
 
   Content(`\`\`\`

package/project/.sdk/src/cmp/cpp/TestClean_cpp.ts

@@ -42,7 +42,7 @@ const TestClean = cmp(function TestClean(props: any) {
     .filter((e: any) => false !== e.active)
     .forEach((entity: any) => {
       const ops = Object.keys(entity.op || {})
-        .filter((op) => ['list', 'load', 'create', 'update', 'remove'].includes(op))
+        .filter((op) => ['list', 'load', 'create', 'update', 'patch', 'remove'].includes(op))
         .sort((a, b) => (rank[a] ?? 2) - (rank[b] ?? 2))
       for (const op of ops) {
         candidates.push({
@@ -74,14 +74,21 @@ function pointParams(opdef: any): string[] {
 
 function candidate(ProjectName: string, c: Candidate): string {
   const call = 'list' === c.op
-    ? `auto ents = c.${c.accessor}()->list(m, ctrl);
-      Value out = vlist();
-      for (const auto& e : ents) out.as_list()->push_back(e->data());
-      return out;`
-    : `return c.${c.accessor}()->${c.op}(m, ctrl)->data();`
+    ? `auto ents = ent->list(m, ctrl);
+        Value out = vlist();
+        for (const auto& e : ents) out.as_list()->push_back(e->data());`
+    : `Value out = ent->${c.op}(m, ctrl)->data();`
   return `    {"${c.name}", {${c.params.map(cppstr).join(', ')}},
-     [](${ProjectName}SDK& c, const Value& m, const Value& ctrl) -> Value {
-      ${call}
+     [](${ProjectName}SDK& c, const Value& m, const Value& ctrl, Value* match) -> Value {
+      auto ent = c.${c.accessor}();
+      try {
+        ${call}
+        if (match) *match = ent->match();
+        return out;
+      } catch (...) {
+        if (match) *match = ent->match();
+        throw;
+      }
     },
      [](${ProjectName}SDK& c, const Value& m, const Value& callopts) -> std::vector<Value> {
       return c.${c.accessor}()->stream(${cppstr(c.op)}, m, callopts);
@@ -343,9 +350,34 @@ static bool hasFeature(const std::string& name) {
 }
 
 
+// Offline, as every generated suite is: the test OPTION resolves a required
+// server variable to test-<name>, and installs no transport.
+static Value offline(const Value& opts) {
+  Value out = vmap();
+  if (opts.is_map()) {
+    for (const auto& kv : *opts.as_map()) map_put(out, kv.first, kv.second);
+  }
+  map_put(out, "test", vmap({{"active", Value(true)}}));
+  return out;
+}
+
+// A client the sweep cannot build leaves nothing swept: a harness error, not
+// a leak.
+static std::shared_ptr<${ProjectName}SDK> construct(const Value& opts) {
+  const std::string harness = "clean harness: the client could not be constructed, so nothing was swept: ";
+  try {
+    return std::make_shared<${ProjectName}SDK>(offline(opts));
+  } catch (const SdkErrorPtr& e) {
+    throw std::runtime_error(harness + e->msg);
+  } catch (const std::exception& e) {
+    throw std::runtime_error(harness + e.what());
+  }
+}
+
 static std::shared_ptr<${ProjectName}SDK> makeSdk(const Scenario& scenario, std::vector<Sink>* sinks,
                                               const Value& cleanopts,
-                                              FeaturePtr extra = nullptr) {
+                                              FeaturePtr extra = nullptr,
+                                              const Value& auth = Value::undef()) {
   Value feature = vmap();
   if (hasFeature("log")) {
     // The log feature hands [level, record] to its logger.
@@ -387,7 +419,8 @@ static std::shared_ptr<${ProjectName}SDK> makeSdk(const Scenario& scenario, std:
     {"feature", feature},
     {"system", vmap({{"fetch", Value(fetch)}})},
   });
-  auto sdk = std::make_shared<${ProjectName}SDK>(opts);
+  if (auth.is_map()) map_put(opts, "auth", auth);
+  auto sdk = construct(opts);
   sdk->getRootCtx()->utility->featureAdd(sdk->getRootCtx(), std::make_shared<CaptureFeature>(sinks));
   if (extra) sdk->getRootCtx()->utility->featureAdd(sdk->getRootCtx(), extra);
   return sdk;
@@ -397,7 +430,8 @@ static std::shared_ptr<${ProjectName}SDK> makeSdk(const Scenario& scenario, std:
 struct Candidate {
   std::string name;
   std::vector<std::string> params;
-  std::function<Value(${ProjectName}SDK&, const Value&, const Value&)> run;
+  // The operation's data, and the match its entity then holds.
+  std::function<Value(${ProjectName}SDK&, const Value&, const Value&, Value*)> run;
   std::function<std::vector<Value>(${ProjectName}SDK&, const Value&, const Value&)> stream;
 };
 
@@ -427,13 +461,13 @@ static Target usableOp(const std::vector<Candidate>& cands) {
     {"apikey", Value(CANARY_APIKEY)},
     {"system", vmap({{"fetch", Value(fetch)}})},
   });
-  auto plain = std::make_shared<${ProjectName}SDK>(opts);
+  auto plain = construct(opts);
   for (size_t i = 0; i < cands.size(); i++) {
     Value filled = vmap();
     for (const auto& p : cands[i].params) map_put(filled, p, Value("p1"));
     for (const Value& match : {vmap(), filled}) {
       try {
-        cands[i].run(*plain, Struct::clone(match), vmap());
+        cands[i].run(*plain, Struct::clone(match), vmap(), nullptr);
         return {static_cast<int>(i), match};
       } catch (const SdkErrorPtr&) {
         continue;
@@ -456,9 +490,10 @@ static SdkErrorPtr drive(${ProjectName}SDK& sdk, const Candidate& cand, const Ta
   Value held = getp(ctrl, "explain");
   SdkErrorPtr err;
   Value out = Value::undef();
+  Value match = Value::undef();
   bool got = false;
   try {
-    out = cand.run(sdk, Struct::clone(target.match), ctrl);
+    out = cand.run(sdk, Struct::clone(target.match), ctrl, &match);
     got = true;
   } catch (const SdkErrorPtr& e) {
     err = e;
@@ -468,6 +503,8 @@ static SdkErrorPtr drive(${ProjectName}SDK& sdk, const Candidate& cand, const Ta
   }
   if (err) addError(sinks, "error", err);
   if (got) addForms(sinks, "result", out);
+  // Raw, as a caller copying the match into another query reads it.
+  addForms(sinks, "match", match);
   Value explain = getp(ctrl, "explain");
   if (explain.is_map()) addForms(sinks, "explain", explain);
   if (held.is_map() && (!explain.is_map() || held.as_map() != explain.as_map())) {
@@ -518,14 +555,19 @@ static void no_credential_leaves_the_sdk() {
     }
   }
 
+  // A name given at run time replaces the declared one: the match leaves out
+  // whichever name prepareAuth placed.
+  drive(*makeSdk(scenarios()[0], &sinks, Value::undef(), nullptr, vmap({{"name", Value("zzcred")}})),
+        cand, target, vmap(), sinks);
+
   // A credential mistyped as a map is rejected by validation, whose message
   // quotes the value it rejected.
   SdkErrorPtr rejected;
   try {
-    std::make_shared<${ProjectName}SDK>(vmap({
+    std::make_shared<${ProjectName}SDK>(offline(vmap({
       {"apikey", vmap({{"value", Value(CANARY_APIKEY)}})},
       {"clean", vmap({{"values", Value(CANARY_VALUE)}})},
-    }));
+    })));
   } catch (const SdkErrorPtr& e) {
     rejected = e;
   }
@@ -585,7 +627,7 @@ static void no_credential_leaves_the_sdk() {
     Value url = vs::getelem(args, Value(int64_t(0)));
     return notfoundsc.respond(url.is_string() ? url.as_string() : "", vs::getelem(args, Value(int64_t(1))));
   };
-  auto bare = std::make_shared<${ProjectName}SDK>(vmap({
+  auto bare = construct(vmap({
     {"apikey", Value(CANARY_APIKEY)},
     {"secret", Value(CANARY_SECRET)},
     {"headers", vmap({{"X-Custom-Token", Value(CANARY_HEADER)}})},
@@ -694,7 +736,7 @@ static void the_sweep_can_see_a_leak() {
 // A registered value used as a property name is masked; names that mask
 // alike are all kept.
 static void a_registered_value_used_as_a_name_is_masked() {
-  auto sdk = std::make_shared<${ProjectName}SDK>(vmap({
+  auto sdk = construct(vmap({
     {"clean", vmap({{"values", Value("ZZVAL-abc123,ZZVAL-xyz789")}})},
   }));
   Value out = util::clean(sdk->getRootCtx(), vmap({
@@ -709,7 +751,7 @@ static void a_registered_value_used_as_a_name_is_masked() {
 
 // The generated config's own clean block is honoured, and left unchanged.
 static void the_generated_configs_own_clean_block_is_honoured() {
-  auto client = std::make_shared<${ProjectName}SDK>(vmap());
+  auto client = construct(vmap());
   UtilityPtr utility = client->getUtility();
   Value config = vmap({{"options", vmap({{"clean", vmap({
     {"keys", Value("zzsens")}, {"values", Value("CONFIG-SEEDED-1")},
@@ -735,14 +777,18 @@ static void the_generated_configs_own_clean_block_is_honoured() {
 // A feature's name is not a field name: a feature called secrets does not
 // make its settings secret, though a sensitive field inside it still is. An
 // entity block, of per-entity settings or seeded records keyed by entity name
-// and id, is not read at all.
+// and id, is not read at all, and nor are rbac's rules, keyed by entity and
+// operation names.
 static void a_feature_name_is_read_as_a_name() {
-  auto client = std::make_shared<${ProjectName}SDK>(vmap({
+  auto client = construct(vmap({
     {"apikey", Value(CANARY_APIKEY)},
     {"feature", vmap({
       {"secrets", vmap({
         {"active", Value(false)}, {"name", Value("ZZNAME-feat123")}, {"token", Value("ZZTOKEN-feat456")},
       })},
+      {"rbac", vmap({
+        {"active", Value(false)}, {"rules", vmap({{"zztoken.load", Value("PLAINRULE-k7j5h3g1")}})},
+      })},
       {"test", vmap({
         {"active", Value(false)},
         {"entity", vmap({{"zztoken", vmap({{"ZZTOKEN01", vmap({{"note", Value("PLAINRECORD-t5r3e1w9")}})}})}})},
@@ -757,6 +803,8 @@ static void a_feature_name_is_read_as_a_name() {
                 Value("record PLAINRECORD-t5r3e1w9"), "a record seeded under an entity block is not registered");
   ASSERT_EQ_VAL(util::clean(ctx, Value("alias PLAINALIAS-m2n4b6v8")),
                 Value("alias PLAINALIAS-m2n4b6v8"), "an entity's own settings are not registered");
+  ASSERT_EQ_VAL(util::clean(ctx, Value("rule PLAINRULE-k7j5h3g1")),
+                Value("rule PLAINRULE-k7j5h3g1"), "an rbac rule keyed by entity and operation is not registered");
 }