@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/src/cmp/perl/PrepareAuth_perl.ts

@@ -112,15 +112,23 @@ my $__dir;
 BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
 require(Cwd::abs_path("$__dir/../lib/Voxgig/Struct.pm"));
 require(Cwd::abs_path("$__dir/../core/helpers.pm"));
-
+${'cookie' === spec.where ? 'require(Cwd::abs_path("$__dir/prepare_headers.pm"));\n' : ''}
 package ${spec.Name}Utilities;
 
 our %REGISTRY;
 
 ${placementNote(spec)}my $CRED_NAME = ${cred};
-my $OPTION_APIKEY = 'apikey';
+${'cookie' === spec.where ? `my $COOKIE_HEADER = 'cookie';
+` : ''}my $OPTION_APIKEY = 'apikey';
 ${secretConst}my $NOT_FOUND = '__NOTFOUND__';
 
+# The client's auth.name option, when set, replaces the name the API declares.
+my $auth_name = sub {
+  my ($options) = @_;
+  my $name = ${spec.Name}Helpers::gpath($options, 'auth.name');
+  return (defined $name && !ref $name && '' ne $name) ? ${'header' === spec.where ? 'lc($name)' : '$name'} : $CRED_NAME;
+};
+${cookieHelper(spec)}
 $REGISTRY{prepare_auth} = sub {
   my ($ctx) = @_;
   my $spec = $ctx->{spec};
@@ -130,10 +138,16 @@ $REGISTRY{prepare_auth} = sub {
 ${bag(spec)}  my $options = $ctx->{client}->options_map;
 
   # Public APIs that need no auth omit the options.auth block entirely.
-${noCredNote(spec)}  if (!defined ${spec.Name}Helpers::gp($options, 'auth')) {
-${clear(spec, '    ')}    return ($spec, undef);
+  if (!defined ${spec.Name}Helpers::gp($options, 'auth')) {
+${clear(spec, '$CRED_NAME', '    ')}    return ($spec, undef);
   }
 
+  my $name = $auth_name->($options);
+
+  # A credential left under the declared name would travel beside the renamed one.
+  if ($name ne $CRED_NAME) {
+${clear(spec, '$CRED_NAME', '    ')}  }
+
   my $apikey = Voxgig::Struct::getprop($options, $OPTION_APIKEY, $NOT_FOUND);
 ${basicBlock(spec, wantBasic)}${credBlock(spec)}
   return ($spec, undef);
@@ -154,32 +168,37 @@ const MISSING = `  if (!defined $apikey || Voxgig::Struct::is_none($apikey)
 
 
 function credBlock(spec: AuthSpec): string {
-  if ('cookie' === spec.where) {
-    return `
-${MISSING}
-    return ($spec, undef);
-  }
-
-${place(spec).replace(/^ {4}/gm, '  ')}`
-  }
-
   return `
 ${MISSING}
-${clear(spec, '    ')}  }
+${clear(spec, '$name', '    ')}  }
   else {
 ${place(spec)}  }
 `
 }
 
 
-function noCredNote(spec: AuthSpec): string {
+// The cookie header is shared with whatever cookies the caller set, so the
+// credential's pair is spliced in and out rather than appended.
+function cookieHelper(spec: AuthSpec): string {
   if ('cookie' !== spec.where) {
     return ''
   }
 
-  return `  # Nothing of OURS to remove either way: this SDK appends its pair to
-  # whatever cookie header the caller set and never stores one, and
-  # prepare_headers rebuilds that header from options on every request.
+  return `
+# Rewrite the cookie header with the named pair removed, then set to VALUE
+# when VALUE is defined; every other cookie is kept in order.
+my $set_cookie = sub {
+  my ($headers, $name, $value) = @_;
+  my $existing = $headers->{$COOKIE_HEADER};
+  my @kept = defined $existing && !ref $existing ? @{ cookie_keep($existing, { $name => 1 }) } : ();
+  push @kept, "$name=$value" if defined $value;
+  if (@kept) {
+    $headers->{$COOKIE_HEADER} = join('; ', @kept);
+  }
+  else {
+    delete $headers->{$COOKIE_HEADER};
+  }
+};
 `
 }
 
@@ -215,16 +234,16 @@ function bag(spec: AuthSpec): string {
 }
 
 
-function clear(spec: AuthSpec, ind: string): string {
+function clear(spec: AuthSpec, name: string, ind: string): string {
   if ('query' === spec.where) {
-    return `${ind}delete $query->{$CRED_NAME};\n`
+    return `${ind}delete $query->{${name}};\n`
   }
 
   if ('cookie' === spec.where) {
-    return ''
+    return `${ind}$set_cookie->($headers, ${name}, undef);\n`
   }
 
-  return `${ind}delete $headers->{$CRED_NAME};\n`
+  return `${ind}delete $headers->{${name}};\n`
 }
 
 
@@ -234,19 +253,15 @@ function place(spec: AuthSpec): string {
     # any API reads. The prefix is a header convention, and is dropped
     # here deliberately rather than silently concatenated. make_url
     # url-encodes both the name and the value.
-    $query->{$CRED_NAME} = (!ref $apikey) ? "$apikey" : '';
+    $query->{$name} = (!ref $apikey) ? "$apikey" : '';
 `
   }
 
   if ('cookie' === spec.where) {
     return `    my $apikey_val = (!ref $apikey) ? "$apikey" : '';
-    my $pair = "$CRED_NAME=$apikey_val";
-    # APPEND, never clobber: the caller's own cookie header may already
-    # carry a session or consent pair that the API needs alongside this
-    # credential.
-    my $cookie = $headers->{'cookie'};
-    $cookie = '' unless defined $cookie && !ref $cookie;
-    $headers->{'cookie'} = ('' eq $cookie) ? $pair : "$cookie; $pair";
+    # Spliced in, replacing an earlier pair of the same name, beside any
+    # session or consent pair the caller's own cookie header carries.
+    $set_cookie->($headers, $name, $apikey_val);
 `
   }
 
@@ -254,7 +269,7 @@ function place(spec: AuthSpec): string {
     $auth_prefix = '' unless defined $auth_prefix && !ref $auth_prefix;
     my $apikey_val = (!ref $apikey) ? "$apikey" : '';
     # Empty prefix (raw apiKey credential) must not add a leading space.
-    $headers->{$CRED_NAME} =
+    $headers->{$name} =
       ('' eq $auth_prefix) ? $apikey_val : "$auth_prefix $apikey_val";
 `
 }
@@ -282,7 +297,7 @@ function basicBlock(spec: AuthSpec, wantBasic: boolean): string {
       || (!ref $secret && ($secret eq $NOT_FOUND || $secret eq ''));
 
     if ($no_apikey) {
-      delete $headers->{$CRED_NAME};
+      delete $headers->{$name};
     }
     else {
       my $auth_prefix = ${spec.Name}Helpers::gpath($options, 'auth.prefix');
@@ -294,7 +309,7 @@ function basicBlock(spec: AuthSpec, wantBasic: boolean): string {
       # The joined, encoded pair is a wire form neither credential's own
       # registration covers.
       $ctx->{utility}{clean_add}->($ctx, $b64);
-      $headers->{$CRED_NAME} =
+      $headers->{$name} =
         ('' eq $auth_prefix) ? $b64 : "$auth_prefix $b64";
     }
 

package/project/.sdk/src/cmp/perl/ReadmeEntity_perl.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -37,6 +37,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list()',        desc: 'List entities, optionally matching the given criteria.' },
   create: { method: 'create($data)', desc: 'Create a new entity with the given data.' },
   update: { method: 'update($data)', desc: 'Update an existing entity.' },
+  patch:  { method: 'patch($data)',  desc: 'Change part of an existing entity.' },
   remove: { method: 'remove($match)', desc: 'Remove the matching entity.' },
 }
 
@@ -62,6 +63,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
     const eVar = entity.name
@@ -116,7 +119,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       // The id key plus every REQUIRED match key (parent path params like
       // page_id) — the same shape the runtime resolves path params from, so
       // the example always works.
@@ -138,17 +141,19 @@ my $${eVar} = $client->${entity.Name}->load(${loadArg});
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`perl
+# an arrayref of entities, one per record; data_get reads each record
 my $${eVar}s = $client->${entity.Name}->list;
+print $_->data_get->{id}, "\\n" for @$${eVar}s;
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear — including a
       // required id and parent keys like page_id — with a real, executable

package/project/.sdk/src/cmp/perl/ReadmeExamplesTest_perl.ts

@@ -144,7 +144,7 @@ sub runnable {
   my ($b) = @_;
   return 1 if $b =~ /\\Q$SDK_CLASS\\E->(?:new|test)\\b/;
   return 1 if $b =~ /\\\$client\\b/;
-  return 1 if $b =~ /->(?:load|list|create|update|remove)\\b/;
+  return 1 if $b =~ /->(?:load|list|create|update|patch|remove)\\b/;
   return 0;
 }
 
@@ -155,7 +155,7 @@ sub looks_sdk {
   my ($b) = @_;
   return 1 if $b =~ /\\\$client\\b/;
   return 1 if $b =~ /\\b\\Q$SDK_CLASS\\E\\b/;
-  return 1 if $b =~ /->(?:load|list|create|update|remove)\\b/;
+  return 1 if $b =~ /->(?:load|list|create|update|patch|remove)\\b/;
   for my $name (keys %ENTITIES) {
     return 1 if $b =~ /->\\Q$name\\E\\b/;
   }

package/project/.sdk/src/cmp/perl/ReadmeHowto_perl.ts

@@ -35,7 +35,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = ''
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `{ '${idF}' => 'test01' }` : ''
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)

package/project/.sdk/src/cmp/perl/ReadmeInstall_perl.ts

@@ -1,11 +1,17 @@
 
 import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
 
+import { minPerl, perlVersionLabel } from './utility_perl'
+
 
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
+  Content(`The SDK needs perl ${perlVersionLabel(minPerl(model, target))} or later.
+
+`)
+
   if (isPublished(model, target.name)) {
     Content(`\`\`\`bash
 ${installCommand(model, target.name)}
@@ -25,9 +31,9 @@ cpanm .
   // Publish pending: not yet on CPAN. This is a pure-Perl SDK with zero
   // non-core runtime deps, so the simplest install is to add the SDK's
   // \`lib\` directory to Perl's module search path (\`@INC\`).
-  const { releasesUrl } = repoInfo(model)
-  Content(`This package is not yet published to CPAN. Install it from the GitHub
-release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) or
+  const { hostName, tagsUrl } = repoInfo(model)
+  Content(`This package is not yet published to CPAN. Install it from the ${hostName}
+release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})) or
 from a source checkout.
 
 The SDK is pure Perl with zero non-core runtime dependencies, so no build

package/project/.sdk/src/cmp/perl/ReadmeIntro_perl.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,7 +10,7 @@ import {
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
-  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const info = modelText(model)
   const tagline = info.tagline || ''
 
   Content(`# ${model.Name} ${target.title} SDK
@@ -36,7 +36,7 @@ following idiomatic Perl 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/perl/ReadmeModel_perl.ts

@@ -20,12 +20,13 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
     load: '| `load` | `($reqmatch, $ctrl) -> hashref` | Load a single entity by match criteria. Dies on error. |',
-    list: '| `list` | `($reqmatch, $ctrl) -> arrayref` | List entities matching the criteria. Dies on error. |',
+    list: '| `list` | `($reqmatch, $ctrl) -> arrayref` | List entities matching the criteria. Resolves to one entity per record. Dies on error. |',
     create: '| `create` | `($reqdata, $ctrl) -> hashref` | Create a new entity. Dies on error. |',
     update: '| `update` | `($reqdata, $ctrl) -> hashref` | Update an existing entity. Dies on error. |',
+    patch: '| `patch` | `($reqdata, $ctrl) -> hashref` | Change part of an existing entity. Dies on error. |',
     remove: '| `remove` | `($reqmatch, $ctrl) -> hashref` | Remove an entity. Dies 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)
@@ -93,9 +94,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data_get for the record) (a \`hashref\` for single-entity
-ops, an \`arrayref\` for \`list\`) and die on error. Wrap calls in
-\`eval { ... }\` and inspect \`$@\` to handle failures.
+Entity operations return the entity, and \`list\` an \`arrayref\` of
+entities, one per record; \`data_get\` reads an entity's record (a
+\`hashref\`). They die on error, so wrap calls in \`eval { ... }\` and
+inspect \`$@\` to handle failures.
 
 The \`direct()\` escape hatch never dies — it returns a result \`hashref\`
 you branch on via \`$result->{ok}\`:

package/project/.sdk/src/cmp/perl/ReadmeQuick_perl.ts

@@ -66,8 +66,8 @@ my $client = ${ctor};
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` returns an \`arrayref\` of records (each a \`hashref\`) and dies on
-error — iterate it directly.
+\`list()\` returns an \`arrayref\` of entities, one per record, and dies on
+error; \`data_get\` reads each record.
 
 \`\`\`perl
 my $${eVar}s = eval { $client->${eName}->list };
@@ -76,7 +76,7 @@ if (my $err = $@) {
 }
 else {
     for my $${eVar} (@$${eVar}s) {
-        print "$${eVar}->{id}\\n";
+        print $${eVar}->data_get->{id}, "\\n";
     }
 }
 \`\`\`
@@ -172,7 +172,8 @@ else {
       ? `$created->{${dataIdF}}`
       : perlLit(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
 
 \`\`\`perl
@@ -189,6 +190,13 @@ my $created = $client->${eName}->create({ ${examplePairs('create').join(', ')} }
         Content(`# Update${fromCreated ? " — the created record's id is a plain hash key" : ''}
 $client->${eName}->update({ ${updatePairs.join(', ')} });
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`'${idF}' => ${idValueFor('patch')}`] : []).concat(examplePairs('patch'))
+        Content(`# Patch — sends only the fields given
+$client->${eName}->patch({ ${patchPairs.join(', ')} });
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/perl/ReadmeRef_perl.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 {
@@ -38,8 +38,8 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   },
   list: {
     sig: 'list($reqmatch, $ctrl) -> arrayref',
-    returns: 'an arrayref of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list` with no argument to list all records. Returns an arrayref and dies on error.',
+    returns: 'an arrayref of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call `list` with no argument to list all records. Returns an arrayref of entities, one per record (`data_get` reads each record), and dies on error.',
   },
   create: {
     sig: 'create($reqdata, $ctrl) -> hashref',
@@ -51,6 +51,11 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
     returns: 'the updated entity data',
     desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and dies on error.',
   },
+  patch: {
+    sig: 'patch($reqdata, $ctrl) -> hashref',
+    returns: 'the patched entity data',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity data and dies on error.',
+  },
   remove: {
     sig: 'remove($reqmatch, $ctrl) -> hashref',
     returns: 'the removed entity data',
@@ -218,7 +223,7 @@ my $${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
 
@@ -259,6 +264,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)
@@ -279,7 +288,7 @@ my $result = $client->${ent.Name}->${opname}(${arg});
             Content(`\`\`\`perl
 my $results = $client->${ent.Name}->list;
 for my $${eVar} (@$results) {
-    print "$${eVar}->{id}\\n";
+    print $${eVar}->data_get->{id}, "\\n";
 }
 \`\`\`
 
@@ -300,8 +309,8 @@ my $result = $client->${ent.Name}->create({
 
 `)
           }
-          else if ('update' === opname) {
-            const updateItems = opRequestShape(ent, 'update').items
+          else if ('update' === opname || 'patch' === opname) {
+            const updateItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
@@ -309,13 +318,21 @@ my $result = $client->${ent.Name}->create({
               `    '${it.name}' => ${perlLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`perl
-my $result = $client->${ent.Name}->update({
-${updateLines}    # Fields to update
+my $result = $client->${ent.Name}->${opname}({
+${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 string, a character string, sent as UTF-8, or a filehandle',
+              once: 'a filehandle',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/perl/ReadmeTopQuick_perl.ts

@@ -49,10 +49,10 @@ my $client = ${ctor};
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`# List all ${eName.toLowerCase()}s (returns an arrayref; dies on error)
+      Content(`# List all ${eName.toLowerCase()}s (an arrayref of entities, one per record; dies on error)
 my $${eVar}s = $client->${eName}->list;
 for my $${eVar} (@$${eVar}s) {
-    print "$${eVar}->{id}\\n";
+    print $${eVar}->data_get->{id}, "\\n";
 }
 `)
     }

package/project/.sdk/src/cmp/perl/ReadmeTopTest_perl.ts

@@ -52,7 +52,7 @@ my $client = ${model.const.Name}SDK->test(undef, undef);
         ? `{ ${items.map((it: any) =>
           `'${it.name}' => ${it.name === idF ? "'test01'" : perlLit(it.type)}`).join(', ')} }`
         : ''
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)

package/project/.sdk/src/cmp/perl/TestClean_perl.ts

@@ -311,8 +311,25 @@ sub has_feature {
   return (Voxgig::Struct::ismap($f) && defined $f->{$name}) ? 1 : 0;
 }
 
+# Offline, as every generated suite is: the test OPTION resolves a required
+# server variable to test-<name>, and installs no transport.
+sub offline {
+  my ($opts) = @_;
+  return { %$opts, 'test' => { 'active' => 1 } };
+}
+
+# A client the sweep cannot build leaves nothing swept: a harness error, not a
+# leak.
+sub construct {
+  my ($opts) = @_;
+  my $client = eval { ${Name}SDK->new(offline($opts)) };
+  die "clean harness: the client could not be constructed, so nothing was swept: $@"
+    unless defined $client;
+  return $client;
+}
+
 sub make_sdk {
-  my ($scenario, $sinks, $cleanopts, $extra) = @_;
+  my ($scenario, $sinks, $cleanopts, $extra, $auth) = @_;
   my $capture = sub {
     my ($name) = @_;
     return sub { push @$sinks, forms($name, $_[0]); return };
@@ -330,7 +347,7 @@ sub make_sdk {
   $feature{clienttrack} = { 'active' => 1 } if has_feature('clienttrack');
 
   my $respond = $scenario->[1];
-  return ${Name}SDK->new({
+  my $opts = {
     'apikey' => $CANARY{apikey},
     'secret' => $CANARY{secret},
     'headers' => { 'X-Custom-Token' => $CANARY{header} },
@@ -341,7 +358,9 @@ sub make_sdk {
       my (undef, $url, $fetchdef) = @_;
       return $respond->($url, $fetchdef);
     } },
-  });
+  };
+  $opts->{auth} = $auth if defined $auth;
+  return construct($opts);
 }
 
 # The first operation that completes against a plain 200: with no
@@ -349,7 +368,7 @@ sub make_sdk {
 # An entity accessor is a capitalised client method whose result answers
 # get_name, as the feature corpus runner finds them.
 sub usable_op {
-  my $plain = ${Name}SDK->new({
+  my $plain = construct({
     'apikey' => $CANARY{apikey},
     'utility' => { 'fetcher' => sub { return (response(200, { 'id' => 'i1' }), undef) } },
   });
@@ -372,7 +391,7 @@ sub usable_op {
   my $entities = ${Name}Config::shared_config()->{entity} || {};
   for my $entname (sort keys %found) {
     my $accessor = $found{$entname};
-    for my $op (qw(list load create update remove)) {
+    for my $op (qw(list load create update patch remove)) {
       next unless $plain->$accessor()->can($op);
       my %filled;
       my $opdef = eval { $entities->{$entname}{op}{$op} };
@@ -398,11 +417,14 @@ sub drive {
   # A caller may keep the record it passed rather than read ctrl.explain.
   my $held = $ctrl->{explain};
   my ($acc, $op) = ($target->{accessor}, $target->{op});
+  my $entity = $sdk->$acc();
   my $out;
-  my $ok = eval { $out = $sdk->$acc()->$op({ %{ $target->{match} } }, $ctrl); 1 };
+  my $ok = eval { $out = $entity->$op({ %{ $target->{match} } }, $ctrl); 1 };
   my $err = $ok ? undef : $@;
   push @$sinks, forms('error', $err) if defined $err;
   push @$sinks, forms('result', $out) if defined $out;
+  # Raw, as a caller copying the match into another query reads it.
+  push @$sinks, forms('match', $entity->match_get());
   push @$sinks, forms('explain', $ctrl->{explain}) if defined $ctrl->{explain};
   push @$sinks, forms('explain:held', $held) if defined $held && (!defined $ctrl->{explain}
     || Scalar::Util::refaddr($held) != Scalar::Util::refaddr($ctrl->{explain}));
@@ -432,14 +454,19 @@ plan skip_all => 'no operation of this SDK completes against a plain 200; nothin
     }
   }
 
+  # A name given at run time replaces the declared one: the match leaves out
+  # whichever name prepare_auth placed.
+  drive(make_sdk($SCENARIOS[0], \\@sinks, undef, undef, { 'name' => 'zzcred' }),
+    $target, {}, \\@sinks);
+
   # A credential mistyped as a map is rejected by validation, whose message
   # quotes the value it rejected.
   my $rejected;
   eval {
-    ${Name}SDK->new({
+    ${Name}SDK->new(offline({
       'apikey' => { 'value' => $CANARY{apikey} },
       'clean' => { 'values' => $CANARY{value} },
-    });
+    }));
     1;
   } or $rejected = $@;
   ok(defined $rejected, 'a credential mistyped as a map is rejected');
@@ -505,7 +532,7 @@ plan skip_all => 'no operation of this SDK completes against a plain 200; nothin
     "the config's clean block is unchanged");
 
   # With no clean option at all, the schema defaults still apply.
-  my $bare = ${Name}SDK->new({
+  my $bare = construct({
     'apikey' => $CANARY{apikey},
     'secret' => $CANARY{secret},
     'headers' => { 'X-Custom-Token' => $CANARY{header} },
@@ -519,12 +546,14 @@ plan skip_all => 'no operation of this SDK completes against a plain 200; nothin
 
   # 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.
-  my $featured = ${Name}SDK->new({
+  # records keyed by entity name and id, is not read at all, and nor are
+  # rbac's rules, keyed by entity and operation names.
+  my $featured = construct({
     'apikey' => $CANARY{apikey},
     'feature' => {
       'zzsecrets' => { 'active' => 0, 'kind' => 'PLAINSETTING-q8w2e4r6' },
       'zzfeat' => { 'active' => 0, 'apitoken' => 'FEATTOKEN-z9y8x7w6' },
+      'rbac' => { 'active' => 0, 'rules' => { 'zztoken.load' => 'PLAINRULE-k7j5h3g1' } },
       'test' => { 'active' => 0, 'entity' => {
         'zztoken' => { 'ZZTOKEN01' => { 'note' => 'PLAINRECORD-t5r3e1w9' } } } },
     },
@@ -535,6 +564,7 @@ plan skip_all => 'no operation of this SDK completes against a plain 200; nothin
   my $ftoken = $fclean->($featured->get_root_ctx(), 'token FEATTOKEN-z9y8x7w6');
   my $frecord = $fclean->($featured->get_root_ctx(), 'record PLAINRECORD-t5r3e1w9');
   my $falias = $fclean->($featured->get_root_ctx(), 'alias PLAINALIAS-m2n4b6v8');
+  my $frule = $fclean->($featured->get_root_ctx(), 'rule PLAINRULE-k7j5h3g1');
 
   my @leaked = grep { @{ $_->{found} } }
     map { { 'name' => $_->{name}, 'found' => [ leaks($_->{text}) ] } } @sinks;
@@ -578,6 +608,7 @@ plan skip_all => 'no operation of this SDK completes against a plain 200; nothin
   is($ftoken, "token $MASK", 'a sensitive setting inside a feature registers');
   is($frecord, 'record PLAINRECORD-t5r3e1w9', 'the records a test entity block seeds do not register');
   is($falias, 'alias PLAINALIAS-m2n4b6v8', 'a per-entity setting does not register');
+  is($frule, 'rule PLAINRULE-k7j5h3g1', 'an rbac rule keyed by entity and operation does not register');
 
   my $explained = $explains{'ok/explain'} || {};
   ok(defined $explained->{result}, 'the explain record carries the result');