@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/c/ReadmeQuick_c.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { cIdent, cVarName } from './utility_c'
+import { cIdent, cVarName, cListMatch } from './utility_c'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -37,6 +37,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // A type-correct C expression constructing a voxgig struct Value.
   const cLit = (type: any, placeholder: string = 'example'): string => {
     const k = canonScalarKey(type)
+    if ('NULL' === k) return 'v_null()'
     if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
     if ('BOOLEAN' === k) return 'v_bool(true)'
     if ('ARRAY' === k) return 'v_list()'
@@ -73,17 +74,18 @@ PNError* err = NULL;
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` returns a List of records and sets \`*err\` on failure — check
-\`err\` after the call.
+\`list()\` returns a \`NULL\`-terminated array of entities, one per record,
+and sets \`*err\` on failure — check \`err\` after the call. \`vt->data\`
+reads an entity's record.
 
 \`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+Entity** ${evar}s = ${evar}->vt->list(${evar}, ${cListMatch(exampleEntity)}, NULL, &err);
 if (err) {
     fprintf(stderr, "list failed: %s\\n", err->msg);
 } else {
-    for (size_t i = 0; i < (size_t)voxgig_size(${evar}s); i++) {
-        printf("%s\\n", voxgig_to_json(voxgig_getelem(${evar}s, v_int(i), NULL)));
+    for (size_t i = 0; ${evar}s[i]; i++) {
+        printf("%s\\n", voxgig_to_json(${evar}s[i]->vt->data(${evar}s[i], NULL)));
     }
 }
 \`\`\`
@@ -112,15 +114,16 @@ if (err) {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record and sets \`*err\` on failure.
+\`load()\` returns the entity and sets \`*err\` on failure; \`vt->data\` reads
+its record.
 
 \`\`\`c
 Entity* ${neVar} = ${neAcc}(client, NULL);
-voxgig_value* ${neVar}_rec = ${neVar}->vt->load(${neVar}, ${neMatch}, NULL, &err);
+Entity* loaded = ${neVar}->vt->load(${neVar}, ${neMatch}, NULL, &err);
 if (err) {
     fprintf(stderr, "load failed: %s\\n", err->msg);
 } else {
-    printf("%s\\n", voxgig_to_json(${neVar}_rec));
+    printf("%s\\n", voxgig_to_json(loaded->vt->data(loaded, NULL)));
 }
 \`\`\`
 
@@ -140,14 +143,15 @@ if (err) {
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record and sets \`*err\` on failure.
+\`load()\` returns the entity and sets \`*err\` on failure; \`vt->data\` reads
+its record.
 
 \`\`\`c
-${acquire}voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+${acquire}Entity* loaded = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
 if (err) {
     fprintf(stderr, "load failed: %s\\n", err->msg);
 } else {
-    printf("%s\\n", voxgig_to_json(${evar}_rec));
+    printf("%s\\n", voxgig_to_json(loaded->vt->data(loaded, NULL)));
 }
 \`\`\`
 
@@ -172,14 +176,16 @@ if (err) {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
     }
-    // The id VALUE for an update/remove match: read it off the returned
-    // `created` record with getp when its data type carries the id AND a
-    // create ran; otherwise a type-correct literal.
-    const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `getp(created, "${dataIdF}")`
+    // The id VALUE for an update/remove match: `created_id`, read off the
+    // created entity's record, when its data type carries the id AND a create
+    // ran; otherwise a type-correct literal.
+    const readsId = null != dataIdF && opnames.includes('create')
+    const idValueFor = (opname: string): string => readsId
+      ? 'created_id'
       : cLit(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')) {
       const acquire = (opnames.includes('list') || opnames.includes('load'))
         ? ''
         : `Entity* ${evar} = ${acc}(client, NULL);\n`
@@ -188,9 +194,14 @@ if (err) {
 \`\`\`c
 ${acquire}`)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record
-voxgig_value* created = ${evar}->vt->create(${evar}, ${cmapExpr(examplePairs('create'))}, NULL, &err);
-
+        const idLine = readsId && (opnames.includes('update') || opnames.includes('remove'))
+          ? `voxgig_value* created_id = created
+    ? getp(created->vt->data(created, NULL), "${dataIdF}") : v_undef();
+`
+          : ''
+        Content(`// Create — returns the created entity, or NULL with *err set
+Entity* created = ${evar}->vt->create(${evar}, ${cmapExpr(examplePairs('create'))}, NULL, &err);
+${idLine}
 `)
       }
       if (opnames.includes('update')) {
@@ -198,6 +209,13 @@ voxgig_value* created = ${evar}->vt->create(${evar}, ${cmapExpr(examplePairs('cr
         Content(`// Update
 ${evar}->vt->update(${evar}, ${cmapExpr(updatePairs)}, NULL, &err);
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`"${idF}", ${idValueFor('patch')}`] : []).concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+${evar}->vt->patch(${evar}, ${cmapExpr(patchPairs)}, NULL, &err);
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/c/ReadmeRef_c.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, 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 { cIdent, cVarName } from './utility_c'
+import { cIdent, cVarName, cListMatch } from './utility_c'
 
 
 // Canonical type sentinel -> a C type name for the field/param tables.
@@ -26,6 +26,7 @@ function cType(type: any): string {
 // A type-correct C expression constructing a voxgig struct Value.
 function cLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'v_null()'
   if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
   if ('BOOLEAN' === k) return 'v_bool(true)'
   if ('ARRAY' === k) return 'v_list()'
@@ -53,24 +54,28 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
 
   const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
     load: {
-      sig: 'vt->load(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
-      desc: 'Load a single entity matching the given criteria. Returns the entity data and sets `*err` on failure.',
+      sig: 'Entity* vt->load(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `vt->data` reads, or `NULL` with `*err` set on failure.',
     },
     list: {
-      sig: 'vt->list(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
-      desc: 'List entities matching the given criteria. The match is optional — pass `NULL` to list all records. Returns a List.',
+      sig: 'Entity** vt->list(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'List entities matching the given criteria. The match is optional — pass `NULL` to list all records. Returns a `NULL`-terminated array of entities, one per record, or `NULL` with `*err` set on failure.',
     },
     create: {
-      sig: 'vt->create(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
-      desc: 'Create a new entity with the given data. Returns the created entity data and sets `*err` on failure.',
+      sig: 'Entity* vt->create(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
+      desc: 'Create a new entity with the given data. Returns the created entity, or `NULL` with `*err` set on failure.',
     },
     update: {
-      sig: 'vt->update(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
-      desc: 'Update an existing entity. The data must include the entity id. Returns the updated entity data.',
+      sig: 'Entity* vt->update(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
+      desc: 'Update an existing entity. The data must include the entity id. Returns the updated entity, or `NULL` with `*err` set on failure.',
+    },
+    patch: {
+      sig: 'Entity* vt->patch(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
+      desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity id. Returns the patched entity, or `NULL` with `*err` set on failure.',
     },
     remove: {
-      sig: 'vt->remove(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
-      desc: 'Remove the entity matching the given criteria. Sets `*err` on failure.',
+      sig: 'Entity* vt->remove(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, or `NULL` with `*err` set on failure.',
     },
   }
 
@@ -219,7 +224,7 @@ Entity* ${evar} = ${acc}(client, 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
 
@@ -260,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)
@@ -270,7 +279,10 @@ ${info.desc}
                 it.name === idF ? ent.name + '_id' : it.name)}`))
             Content(`\`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* result = ${evar}->vt->${opname}(${evar}, ${arg}, NULL, &err);
+Entity* result = ${evar}->vt->${opname}(${evar}, ${arg}, NULL, &err);
+if (result) {
+    printf("%s\\n", voxgig_to_json(result->vt->data(result, NULL)));
+}
 \`\`\`
 
 `)
@@ -278,9 +290,9 @@ voxgig_value* result = ${evar}->vt->${opname}(${evar}, ${arg}, NULL, &err);
           else if ('list' === opname) {
             Content(`\`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* results = ${evar}->vt->list(${evar}, NULL, NULL, &err);
-for (size_t i = 0; i < (size_t)voxgig_size(results); i++) {
-    printf("%s\\n", voxgig_to_json(voxgig_getelem(results, v_int(i), NULL)));
+Entity** results = ${evar}->vt->list(${evar}, ${cListMatch(ent)}, NULL, &err);
+for (size_t i = 0; results && results[i]; i++) {
+    printf("%s\\n", voxgig_to_json(results[i]->vt->data(results[i], NULL)));
 }
 \`\`\`
 
@@ -293,10 +305,10 @@ for (size_t i = 0; i < (size_t)voxgig_size(results); i++) {
 Entity* ${evar} = ${acc}(client, NULL);
 `)
             if (0 === createItems.length) {
-              Content(`voxgig_value* result = ${evar}->vt->create(${evar}, NULL, NULL, &err);
+              Content(`Entity* result = ${evar}->vt->create(${evar}, NULL, NULL, &err);
 `)
             } else {
-              Content(`voxgig_value* result = ${evar}->vt->create(${evar}, cmap(${createItems.length},
+              Content(`Entity* result = ${evar}->vt->create(${evar}, cmap(${createItems.length},
 `)
               createItems.map((it: any, i: number) => {
                 const comma = i < createItems.length - 1 ? ',' : ')'
@@ -310,8 +322,8 @@ Entity* ${evar} = ${acc}(client, NULL);
 
 `)
           }
-          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))
@@ -320,11 +332,18 @@ Entity* ${evar} = ${acc}(client, NULL);
                 it.name === idF ? ent.name + '_id' : it.name)}`)
             Content(`\`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* result = ${evar}->vt->update(${evar}, ${cmapExpr(updatePairs)}, NULL, &err);
+Entity* result = ${evar}->vt->${opname}(${evar}, ${cmapExpr(updatePairs)}, NULL, &err);
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a string value holding the bytes, such as `voxgig_new_string_n`',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/c/ReadmeTopQuick_c.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { cIdent, cVarName } from './utility_c'
+import { cIdent, cVarName, cListMatch } from './utility_c'
 
 
 // A type-correct C expression constructing a voxgig struct Value for a param.
@@ -15,6 +15,7 @@ import { cIdent, cVarName } from './utility_c'
 // typed builder call.
 function cLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'v_null()'
   if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
   if ('BOOLEAN' === k) return 'v_bool(true)'
   if ('ARRAY' === k) return 'v_list()'
@@ -61,10 +62,10 @@ PNError* err = NULL;
     if (opnames.includes('list')) {
       Content(`Entity* ${evar} = ${acc}(client, NULL);
 
-// List all ${eName.toLowerCase()}s (returns a List, sets *err on failure)
-voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
-for (size_t i = 0; i < (size_t)voxgig_size(${evar}s); i++) {
-    printf("%s\\n", voxgig_to_json(voxgig_getelem(${evar}s, v_int(i), NULL)));
+// List all ${eName.toLowerCase()}s (one entity per record, sets *err on failure)
+Entity** ${evar}s = ${evar}->vt->list(${evar}, ${cListMatch(exampleEntity)}, NULL, &err);
+for (size_t i = 0; ${evar}s && ${evar}s[i]; i++) {
+    printf("%s\\n", voxgig_to_json(${evar}s[i]->vt->data(${evar}s[i], NULL)));
 }
 `)
     }
@@ -84,9 +85,11 @@ for (size_t i = 0; i < (size_t)voxgig_size(${evar}s); i++) {
         ? ''
         : `Entity* ${evar} = ${acc}(client, NULL);\n`
       Content(`
-${acquire}// Load a specific ${eName.toLowerCase()} (returns the record, sets *err on failure)
-voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
-printf("%s\\n", voxgig_to_json(${evar}_rec));
+${acquire}// Load a specific ${eName.toLowerCase()} (returns the entity, sets *err on failure)
+Entity* loaded = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+if (loaded) {
+    printf("%s\\n", voxgig_to_json(loaded->vt->data(loaded, NULL)));
+}
 `)
     }
   }

package/project/.sdk/src/cmp/c/ReadmeTopTest_c.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,13 +7,14 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { cIdent, cVarName } from './utility_c'
+import { cIdent, cVarName, cString } from './utility_c'
 
 
 // A type-correct C expression constructing a voxgig struct Value for a field's
 // canonical type.
 function cLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'v_null()'
   if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
   if ('BOOLEAN' === k) return 'v_bool(true)'
   if ('ARRAY' === k) return 'v_list()'
@@ -52,27 +53,38 @@ PNError* err = 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 match.
-      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 = cmapExpr(items.map((it: any) =>
-        `"${it.name}", ${it.name === idF ? 'v_str("test01")' : cLit(it.type)}`))
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+        `${cString(it.name)}, ${isMatchOp && it.name === idF ? 'v_str("test01")' : cLit(it.type)}`))
+    } 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 = cmapExpr(chosen.map((it: any) => `"${it.name}", ${cLit(it.type)}`))
+      arg = cmapExpr(chosen.map((it: any) => `${cString(it.name)}, ${cLit(it.type)}`))
     }
-    const resVar = cVarName(exampleEntity.name) + ('list' === primaryOp ? 's' : '_rec')
     Content(`Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${resVar} = ${evar}->vt->${primaryOp}(${evar}, ${arg}, NULL, &err);
-printf("%s\\n", voxgig_to_json(${resVar}));
 `)
+    if ('list' === primaryOp) {
+      Content(`Entity** ${evar}s = ${evar}->vt->list(${evar}, ${arg}, NULL, &err);
+for (size_t i = 0; ${evar}s && ${evar}s[i]; i++) {
+    printf("%s\\n", voxgig_to_json(${evar}s[i]->vt->data(${evar}s[i], NULL)));
+}
+`)
+    }
+    else {
+      Content(`Entity* result = ${evar}->vt->${primaryOp}(${evar}, ${arg}, NULL, &err);
+if (result) {
+    printf("%s\\n", voxgig_to_json(result->vt->data(result, NULL)));
+}
+`)
+    }
   }
 
   Content(`\`\`\`

package/project/.sdk/src/cmp/c/TestClean_c.ts

@@ -21,7 +21,7 @@ import { cIdent, cVarName } from './utility_c'
 
 
 // A custom action is not a vtable slot the sweep can call by name.
-const CRUD = ['list', 'load', 'create', 'update', 'remove']
+const CRUD = ['list', 'load', 'create', 'update', 'patch', 'remove']
 
 const DIAGNOSTIC = ['log', 'debug', 'audit', 'telemetry', 'cost', 'metrics', 'clienttrack']
 
@@ -98,10 +98,12 @@ function render(spec: {
   const { Name, ident, auth, features, candidates } = spec
 
   const drivers = candidates.map((c) => 'list' === c.op
-    ? `static PNError* ${c.fn}(${Name}SDK* sdk, voxgig_value* mtch, voxgig_value* ctrl, voxgig_value** out) {
+    ? `static PNError* ${c.fn}(${Name}SDK* sdk, voxgig_value* mtch, voxgig_value* ctrl, voxgig_value** out,
+    voxgig_value** match) {
   PNError* err = NULL;
   Entity* e = ${ident}_${c.evar}(sdk, NULL);
   Entity** items = e->vt->list(e, mtch, ctrl, &err);
+  if (match) *match = e->vt->matchv(e, NULL);
   if (err) return err;
   voxgig_value* list = v_list();
   for (size_t i = 0; items && items[i]; i++) {
@@ -111,10 +113,12 @@ function render(spec: {
   return NULL;
 }
 `
-    : `static PNError* ${c.fn}(${Name}SDK* sdk, voxgig_value* mtch, voxgig_value* ctrl, voxgig_value** out) {
+    : `static PNError* ${c.fn}(${Name}SDK* sdk, voxgig_value* mtch, voxgig_value* ctrl, voxgig_value** out,
+    voxgig_value** match) {
   PNError* err = NULL;
   Entity* e = ${ident}_${c.evar}(sdk, NULL);
   Entity* r = e->vt->${c.op}(e, mtch, ctrl, &err);
+  if (match) *match = e->vt->matchv(e, NULL);
   if (err) return err;
   *out = r ? r->vt->data(r, NULL) : v_undef();
   return NULL;
@@ -384,7 +388,16 @@ static voxgig_value* transport_fn(void* ud, voxgig_value* args) {
   return respond(sc, url);
 }
 
-static ${Name}SDK* make_sdk(int sc, voxgig_value* cleanopts, Feature* extra) {
+// Offline, as every generated suite is: the test OPTION resolves a required
+// server variable to test-<name>, and installs no transport. A construction
+// that fails aborts, which no harness can catch, so the option is the guard.
+static voxgig_value* offline(voxgig_value* opts) {
+  setp(opts, "test", cmap(1, "active", v_bool(true)));
+  return opts;
+}
+
+static ${Name}SDK* make_sdk_with(int sc, voxgig_value* cleanopts, Feature* extra,
+    voxgig_value* auth) {
   voxgig_value* feature = v_map();
   for (size_t i = 0; FEATURES[i]; i++) {
     const char* name = FEATURES[i];
@@ -405,13 +418,15 @@ static ${Name}SDK* make_sdk(int sc, voxgig_value* cleanopts, Feature* extra) {
     }
   }
 
-  ${Name}SDK* sdk = ${ident}_sdk_new(cmap(6,
+  voxgig_value* opts = cmap(6,
     "apikey", v_str(CANARY_APIKEY),
     "secret", v_str(CANARY_SECRET),
     "headers", cmap(1, "X-Custom-Token", v_str(CANARY_HEADER)),
     "clean", clean,
     "feature", feature,
-    "system", cmap(1, "fetch", vfn(transport_fn, (void*)(intptr_t)sc))));
+    "system", cmap(1, "fetch", vfn(transport_fn, (void*)(intptr_t)sc)));
+  if (auth) setp(opts, "auth", auth);
+  ${Name}SDK* sdk = ${ident}_sdk_new(offline(opts));
 
   // C options are pure data, so the extension feature is added after
   // construction (the \`extend\` option of the ts client).
@@ -423,7 +438,13 @@ static ${Name}SDK* make_sdk(int sc, voxgig_value* cleanopts, Feature* extra) {
   return sdk;
 }
 
-typedef PNError* (*Drive)(${Name}SDK* sdk, voxgig_value* mtch, voxgig_value* ctrl, voxgig_value** out);
+static ${Name}SDK* make_sdk(int sc, voxgig_value* cleanopts, Feature* extra) {
+  return make_sdk_with(sc, cleanopts, extra, NULL);
+}
+
+// What the operation returned, and the match its entity then holds.
+typedef PNError* (*Drive)(${Name}SDK* sdk, voxgig_value* mtch, voxgig_value* ctrl, voxgig_value** out,
+    voxgig_value** match);
 typedef voxgig_value* (*Streamer)(${Name}SDK* sdk, voxgig_value* mtch, voxgig_value* callopts, PNError** err);
 
 ${drivers}
@@ -443,9 +464,9 @@ typedef struct {
 // The first operation that completes against a plain 200: with no
 // arguments, else with every path parameter its points declare filled in.
 static bool usable_op(Target* target) {
-  ${Name}SDK* plain = ${ident}_sdk_new(cmap(2,
+  ${Name}SDK* plain = ${ident}_sdk_new(offline(cmap(2,
     "apikey", v_str(CANARY_APIKEY),
-    "system", cmap(1, "fetch", vfn(transport_fn, (void*)(intptr_t)SC_OK))));
+    "system", cmap(1, "fetch", vfn(transport_fn, (void*)(intptr_t)SC_OK)))));
   for (size_t i = 0; CANDIDATES[i].name; i++) {
     voxgig_value* filled = v_map();
     for (size_t p = 0; CANDIDATES[i].params[p]; p++) {
@@ -454,7 +475,7 @@ static bool usable_op(Target* target) {
     voxgig_value* tries[2] = { v_map(), filled };
     for (int t = 0; t < 2; t++) {
       voxgig_value* out = NULL;
-      PNError* err = CANDIDATES[i].fn(plain, voxgig_clone(tries[t]), NULL, &out);
+      PNError* err = CANDIDATES[i].fn(plain, voxgig_clone(tries[t]), NULL, &out, NULL);
       if (!err) {
         target->fn = CANDIDATES[i].fn;
         target->stream = CANDIDATES[i].stream;
@@ -470,12 +491,15 @@ static PNError* drive(${Name}SDK* sdk, Target* target, voxgig_value* ctrl) {
   // A caller may keep the record it passed rather than read ctrl.explain.
   voxgig_value* held = ctrl ? getp(ctrl, "explain") : NULL;
   voxgig_value* out = NULL;
-  PNError* err = target->fn(sdk, voxgig_clone(target->mtch), ctrl, &out);
+  voxgig_value* match = NULL;
+  PNError* err = target->fn(sdk, voxgig_clone(target->mtch), ctrl, &out, &match);
   if (err) {
     push_error("error", err);
   } else {
     push_value("result", out ? out : v_undef());
   }
+  // Raw, as a caller copying the match into another query reads it.
+  push_value("match", match ? match : v_undef());
   voxgig_value* explain = ctrl ? getp(ctrl, "explain") : NULL;
   if (v_is_map(explain)) push_value("explain", explain);
   if (v_is_map(held) && held != explain) push_value("explain:held", held);
@@ -541,12 +565,16 @@ int main(void) {
     }
   }
 
+  // A name given at run time replaces the declared one: the match leaves
+  // out whichever name prepare_auth placed.
+  drive(make_sdk_with(SC_OK, NULL, NULL, cmap(1, "name", v_str("zzcred"))), op, NULL);
+
   // A credential mistyped as a map. The C validator defaults rather than
   // rejects, so what the constructor produced is swept instead: a string
   // quoting the value, cleaned the way a validation message is.
-  ${Name}SDK* mistyped = ${ident}_sdk_new(cmap(2,
+  ${Name}SDK* mistyped = ${ident}_sdk_new(offline(cmap(2,
     "apikey", cmap(1, "value", v_str(CANARY_APIKEY)),
-    "clean", cmap(1, "values", v_str(CANARY_VALUE))));
+    "clean", cmap(1, "values", v_str(CANARY_VALUE)))));
   {
     char quoted[256];
     snprintf(quoted, sizeof(quoted), "apikey: expected string, got {\\"value\\":\\"%s\\"}",
@@ -595,11 +623,11 @@ int main(void) {
   push("stepped", pn_error_str(stepped));
 
   // A client given no clean block at all masks by the schema defaults.
-  ${Name}SDK* bare = ${ident}_sdk_new(cmap(4,
+  ${Name}SDK* bare = ${ident}_sdk_new(offline(cmap(4,
     "apikey", v_str(CANARY_APIKEY),
     "secret", v_str(CANARY_SECRET),
     "headers", cmap(1, "X-Custom-Token", v_str(CANARY_HEADER)),
-    "system", cmap(1, "fetch", vfn(transport_fn, (void*)(intptr_t)SC_NOTFOUND))));
+    "system", cmap(1, "fetch", vfn(transport_fn, (void*)(intptr_t)SC_NOTFOUND)))));
   PNError* barerr = drive(bare, op, NULL);
   CHECK(barerr != NULL, "the 404 scenario must throw without a clean block");
 
@@ -685,15 +713,15 @@ int main(void) {
   {
     voxgig_value* out = NULL;
     PNError* explained = op->fn(make_sdk(SC_NOTFOUND, cmap(1, "active", v_bool(false)), NULL),
-                                voxgig_clone(op->mtch), cmap(1, "explain", v_map()), &out);
+                                voxgig_clone(op->mtch), cmap(1, "explain", v_map()), &out, NULL);
     CHECK_STR_EQ(explained ? explained->msg : NULL, rawerr ? rawerr->msg : NULL,
                  "with clean off, explain lost the error");
   }
 
   // A registered value used as a property name is masked; names that mask
   // alike are all kept.
-  ${Name}SDK* named = ${ident}_sdk_new(cmap(1,
-    "clean", cmap(1, "values", v_str("ZZVAL-abc123,ZZVAL-xyz789"))));
+  ${Name}SDK* named = ${ident}_sdk_new(offline(cmap(1,
+    "clean", cmap(1, "values", v_str("ZZVAL-abc123,ZZVAL-xyz789")))));
   voxgig_value* renamed = clean_util(sdk_get_root_ctx(named), cmap(3,
     "ZZVAL-abc123", v_num(1), "ZZVAL-xyz789", v_num(2), "plain", v_num(3)));
   voxgig_map* rm = voxgig_as_map(renamed);
@@ -732,21 +760,25 @@ int main(void) {
   // 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.
+  // name and id, is not read at all, and nor are rbac's rules, keyed by entity
+  // and operation names.
   {
-    ${Name}SDK* featured = ${ident}_sdk_new(cmap(3,
+    ${Name}SDK* featured = ${ident}_sdk_new(offline(cmap(3,
       "apikey", v_str(CANARY_APIKEY),
-      "feature", cmap(2,
+      "feature", cmap(3,
         "secrets", cmap(3,
           "active", v_bool(false),
           "name", v_str("ZZNAME-feat123"),
           "token", v_str("ZZTOKEN-feat456")),
+        "rbac", cmap(2,
+          "active", v_bool(false),
+          "rules", cmap(1, "zztoken.load", v_str("PLAINRULE-k7j5h3g1"))),
         "test", cmap(2,
           "active", v_bool(false),
           "entity", cmap(1, "zztoken", cmap(1, "ZZTOKEN01",
             cmap(1, "note", v_str("PLAINRECORD-t5r3e1w9")))))),
       "entity", cmap(1, "zztoken", cmap(1, "alias",
-        cmap(1, "zzkey", v_str("PLAINALIAS-m2n4b6v8"))))));
+        cmap(1, "zzkey", v_str("PLAINALIAS-m2n4b6v8")))))));
     Context* fctx = sdk_get_root_ctx(featured);
     char want[128];
     snprintf(want, sizeof(want), "ZZNAME-feat123 %s", MASK);
@@ -756,6 +788,8 @@ int main(void) {
                  "a record seeded under an entity block is not registered");
     CHECK_STR_EQ(clean_str(fctx, "alias PLAINALIAS-m2n4b6v8"), "alias PLAINALIAS-m2n4b6v8",
                  "an entity's own settings are not registered");
+    CHECK_STR_EQ(clean_str(fctx, "rule PLAINRULE-k7j5h3g1"), "rule PLAINRULE-k7j5h3g1",
+                 "an rbac rule keyed by entity and operation is not registered");
   }
 
   TEST_SUMMARY("clean");

package/project/.sdk/src/cmp/c/TestDirect_c.ts

@@ -151,7 +151,7 @@ int main(void) {
 `)
       for (let i = 0; i < listParams.length; i++) {
         const placeholder = 'direct0' + (i + 1)
-        Content(`    setp(params, "${listParams[i].name}", v_str("${placeholder}"));
+        Content(`    setp(params, "${listParams[i].n}", v_str("${placeholder}"));
 `)
       }
       Content(`    PNError* err = NULL;
@@ -188,7 +188,7 @@ int main(void) {
 `)
       for (let i = 0; i < loadParams.length; i++) {
         const placeholder = 'direct0' + (i + 1)
-        Content(`    setp(params, "${loadParams[i].name}", v_str("${placeholder}"));
+        Content(`    setp(params, "${loadParams[i].n}", v_str("${placeholder}"));
 `)
       }
       Content(`    PNError* err = NULL;