@voxgig/sdkgen 4.33.0 → 4.34.1

package/project/.sdk/src/cmp/py/PrepareAuth_py.ts

@@ -90,7 +90,7 @@ OPTION_APIKEY = "apikey"
 ` + (spec.basic ? `OPTION_SECRET = "secret"
 ` : '') + `NOT_FOUND = "__NOTFOUND__"
 
-
+` + authName('HEADER_AUTH', true) + `
 def prepare_auth_util(ctx):
     spec = ctx.spec
     if spec is None:
@@ -105,6 +105,12 @@ def prepare_auth_util(ctx):
         headers.pop(HEADER_AUTH, None)
         return spec, None
 
+    name = _auth_name(options)
+
+    # A credential left under the declared name would travel beside the renamed one.
+    if name != HEADER_AUTH:
+        headers.pop(HEADER_AUTH, None)
+
     apikey = vs.getprop(options, OPTION_APIKEY, NOT_FOUND)
 ` + basicBlock(spec) + `
     if (
@@ -112,7 +118,7 @@ def prepare_auth_util(ctx):
         or apikey is None
         or apikey == ""
     ):
-        headers.pop(HEADER_AUTH, None)
+        headers.pop(name, None)
     else:
         auth_prefix = ""
         ap = vs.getpath(options, "auth.prefix")
@@ -122,7 +128,7 @@ def prepare_auth_util(ctx):
         if isinstance(apikey, str):
             apikey_val = apikey
         # Empty prefix (raw apiKey credential) must not add a leading space.
-        headers[HEADER_AUTH] = (
+        headers[name] = (
             auth_prefix + " " + apikey_val if auth_prefix else apikey_val
         )
 
@@ -159,7 +165,7 @@ function basicBlock(spec: AuthSpec): string {
         )
 
         if no_apikey:
-            headers.pop(HEADER_AUTH, None)
+            headers.pop(name, None)
         else:
             auth_prefix = ""
             ap = vs.getpath(options, "auth.prefix")
@@ -171,7 +177,7 @@ function basicBlock(spec: AuthSpec): string {
             # The joined, encoded pair is a wire form neither credential's
             # own registration covers.
             ctx.utility.clean_add(ctx, b64)
-            headers[HEADER_AUTH] = (
+            headers[name] = (
                 auth_prefix + " " + b64 if auth_prefix else b64
             )
 
@@ -187,7 +193,7 @@ QUERY_AUTH = ${pystr(spec.name)}
 OPTION_APIKEY = "apikey"
 NOT_FOUND = "__NOTFOUND__"
 
-
+` + authName('QUERY_AUTH', false) + `
 def prepare_auth_util(ctx):
     spec = ctx.spec
     if spec is None:
@@ -202,6 +208,12 @@ def prepare_auth_util(ctx):
         query.pop(QUERY_AUTH, None)
         return spec, None
 
+    name = _auth_name(options)
+
+    # A credential left under the declared name would travel beside the renamed one.
+    if name != QUERY_AUTH:
+        query.pop(QUERY_AUTH, None)
+
     apikey = vs.getprop(options, OPTION_APIKEY, NOT_FOUND)
 
     if (
@@ -209,7 +221,7 @@ def prepare_auth_util(ctx):
         or apikey is None
         or apikey == ""
     ):
-        query.pop(QUERY_AUTH, None)
+        query.pop(name, None)
     else:
         apikey_val = ""
         if isinstance(apikey, str):
@@ -217,7 +229,7 @@ def prepare_auth_util(ctx):
         # NO PREFIX IN A QUERY STRING. \`?${spec.name}=Bearer%20abc\` is not a
         # thing any API reads: the prefix is a header convention, so it is
         # dropped here deliberately rather than silently concatenated.
-        query[QUERY_AUTH] = apikey_val
+        query[name] = apikey_val
 
     return spec, None
 `
@@ -226,36 +238,30 @@ def prepare_auth_util(ctx):
 
 function renderCookie(spec: AuthSpec, head: string): string {
   return head + `from ${spec.pkg}.utility.voxgig_struct import voxgig_struct as vs
+from ${spec.pkg}.utility.prepare_headers import cookie_keep
 
 COOKIE_HEADER = "cookie"
 COOKIE_AUTH = ${pystr(spec.name)}
 OPTION_APIKEY = "apikey"
 NOT_FOUND = "__NOTFOUND__"
 
-
-def _cookies_without_cred(headers):
-    """The cookie header minus our own pair, every other cookie untouched."""
+` + authName('COOKIE_AUTH', false) + `
+def _cookies_without_cred(headers, name):
+    """The cookie header minus the named pair, every other cookie untouched."""
     existing = headers.get(COOKIE_HEADER)
     if not isinstance(existing, str) or existing == "":
         return ""
 
-    kept = []
-    for part in existing.split(";"):
-        piece = part.strip()
-        if piece == "" or piece == COOKIE_AUTH or piece.startswith(COOKIE_AUTH + "="):
-            continue
-        kept.append(piece)
-
-    return "; ".join(kept)
+    return "; ".join(cookie_keep(existing, [name]))
 
 
-def _apply_cookie(headers, value):
-    """Set (value) or remove (None) our pair, leaving the rest in place.
+def _apply_cookie(headers, name, value):
+    """Set (value) or remove (None) the named pair, leaving the rest in place.
 
     Splicing rather than assigning also makes this idempotent: a retried
     request cannot end up with the credential in the header twice.
     """
-    rest = _cookies_without_cred(headers)
+    rest = _cookies_without_cred(headers, name)
 
     if value is None:
         if rest == "":
@@ -264,7 +270,7 @@ def _apply_cookie(headers, value):
             headers[COOKIE_HEADER] = rest
         return
 
-    pair = COOKIE_AUTH + "=" + value
+    pair = name + "=" + value
     headers[COOKIE_HEADER] = rest + "; " + pair if rest else pair
 
 
@@ -279,9 +285,15 @@ def prepare_auth_util(ctx):
 
     # Public APIs that need no auth omit the options.auth block entirely.
     if options.get("auth") is None:
-        _apply_cookie(headers, None)
+        _apply_cookie(headers, COOKIE_AUTH, None)
         return spec, None
 
+    name = _auth_name(options)
+
+    # A credential left under the declared name would travel beside the renamed one.
+    if name != COOKIE_AUTH:
+        _apply_cookie(headers, COOKIE_AUTH, None)
+
     apikey = vs.getprop(options, OPTION_APIKEY, NOT_FOUND)
 
     if (
@@ -289,20 +301,34 @@ def prepare_auth_util(ctx):
         or apikey is None
         or apikey == ""
     ):
-        _apply_cookie(headers, None)
+        _apply_cookie(headers, name, None)
     else:
         apikey_val = ""
         if isinstance(apikey, str):
             apikey_val = apikey
         # NO PREFIX IN A COOKIE either - a cookie carries a bare
         # \`name=value\` pair, not a header's scheme-prefixed credential.
-        _apply_cookie(headers, apikey_val)
+        _apply_cookie(headers, name, apikey_val)
 
     return spec, None
 `
 }
 
 
+// The client's `auth.name` option, when set, replaces the declared name; a
+// header name travels lower-cased.
+function authName(declared: string, header: boolean): string {
+  return `
+def _auth_name(options):
+    name = vs.getpath(options, "auth.name")
+    if isinstance(name, str) and name != "":
+        return ${header ? 'name.lower()' : 'name'}
+    return ${declared}
+
+`
+}
+
+
 function isAuthActive_py(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })

package/project/.sdk/src/cmp/py/ReadmeEntity_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -28,6 +28,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.' },
 }
 
@@ -53,6 +54,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 || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
@@ -110,7 +113,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.
@@ -132,7 +135,7 @@ ${eVar} = client.${entity.Name}().load(${loadArg})
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`python
@@ -142,7 +145,7 @@ ${eVar}s = client.${entity.Name}().list(${listMatchArg(entity)})
 `)
     }
 
-    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/py/ReadmeExamplesTest_py.ts

@@ -224,6 +224,8 @@ def test_readme_python_blocks_typecheck():
         env["PYTHONDONTWRITEBYTECODE"] = "1"
         # Resolve "from _SDK_MODULE import _SDK_CLASS" against the package root.
         env["MYPYPATH"] = _PY_ROOT + os.pathsep + env.get("MYPYPATH", "")
+        # The child writes UTF-8 and the capture reads it, whatever the locale.
+        env["PYTHONIOENCODING"] = "utf-8"
 
         proc = subprocess.run(
             [
@@ -238,6 +240,7 @@ def test_readme_python_blocks_typecheck():
             env=env,
             capture_output=True,
             text=True,
+            encoding="utf-8",
         )
 
         base = os.path.basename(snippet_path)
@@ -263,10 +266,9 @@ def test_readme_python_blocks_typecheck():
 # ----------------------------------------------------------------------------
 
 def _uses_var(block, var):
-    # True if the block reads an attribute off the whole-word variable "var"
-    # (i.e. contains "var." with a non-identifier char, or nothing, before it).
-    # This distinguishes a client-driving "sdk." from the "_sdk." tail of an
-    # import module name.
+    # True if the block reads an attribute off the variable "var", not off a
+    # name that ends in it: "_sdk." in a module name, "-client." in a package
+    # name or a host, ".client." on another object.
     needle = var + "."
     start = 0
     while True:
@@ -276,7 +278,7 @@ def _uses_var(block, var):
         ok_before = True
         if j > 0:
             ch = block[j - 1]
-            if ch.isalnum() or ch == "_":
+            if ch.isalnum() or ch in "_-./\\"'":
                 ok_before = False
         if ok_before:
             return True
@@ -483,6 +485,8 @@ def _run_batch(items, label):
     env = dict(os.environ)
     env["PYTHONDONTWRITEBYTECODE"] = "1"
     env["PYTHONPATH"] = _PY_ROOT + os.pathsep + env.get("PYTHONPATH", "")
+    # The child writes UTF-8 and the capture reads it, whatever the locale.
+    env["PYTHONIOENCODING"] = "utf-8"
 
     # A FILE, not "python -c". The driver embeds every runnable snippet's
     # source, and a large SDK documents hundreds of them: passing that on the
@@ -495,7 +499,7 @@ def _run_batch(items, label):
             fh.write(driver)
         proc = subprocess.run(
             [sys.executable, driver_path],
-            cwd=_PY_ROOT, env=env, capture_output=True, text=True,
+            cwd=_PY_ROOT, env=env, capture_output=True, text=True, encoding="utf-8",
         )
         return (proc.stdout or "") + (proc.stderr or "")
 
@@ -545,6 +549,7 @@ def _run_source(source, label, index):
     env = dict(os.environ)
     env["PYTHONDONTWRITEBYTECODE"] = "1"
     env["PYTHONPATH"] = _PY_ROOT + os.pathsep + env.get("PYTHONPATH", "")
+    env["PYTHONIOENCODING"] = "utf-8"
 
     proc = subprocess.run(
         [sys.executable, "-c", source],
@@ -552,6 +557,7 @@ def _run_source(source, label, index):
         env=env,
         capture_output=True,
         text=True,
+        encoding="utf-8",
     )
     if proc.returncode == 0:
         return None

package/project/.sdk/src/cmp/py/ReadmeHowto_py.ts

@@ -40,7 +40,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testArg = 0 < items.length
       ? `{${items.map((it: any) => `"${it.name}": ${it.name === idF ? '"test01"' : pyLit(it.type)}`).join(', ')}}`
       : ''
-  } 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/py/ReadmeInstall_py.ts

@@ -23,9 +23,9 @@ pip install -e .
 
   // Publish pending: not yet on PyPI. Install from the git release tag or
   // from a local source checkout.
-  const { releasesUrl } = repoInfo(model)
-  Content(`This package is not yet published to PyPI. 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 PyPI. Install it from the ${hostName}
+release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})) or
 from a source checkout:
 
 \`\`\`bash

package/project/.sdk/src/cmp/py/ReadmeIntro_py.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
@@ -35,7 +35,7 @@ The ${target.title} SDK for the ${model.Name} API — an entity-oriented client
   // 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/py/ReadmeModel_py.ts

@@ -25,9 +25,10 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     list: '| `list` | `(reqmatch, ctrl) -> list` | List entities matching the criteria. Raises on error. |',
     create: '| `create` | `(reqdata, ctrl) -> any` | Create a new entity. Raises on error. |',
     update: '| `update` | `(reqdata, ctrl) -> any` | Update an existing entity. Raises on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> any` | Change part of an existing entity. Raises on error. |',
     remove: '| `remove` | `(reqmatch, ctrl) -> any` | Remove an entity. 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)

package/project/.sdk/src/cmp/py/ReadmeQuick_py.ts

@@ -181,7 +181,8 @@ except Exception as err:
       ? `created.data_get()["${dataIdF}"]`
       : pyLit(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
 
 \`\`\`python
@@ -198,6 +199,13 @@ created = client.${eName}().create({${examplePairs('create').join(', ')}})
         Content(`# Update${fromCreated ? " — the created record's id is a plain dict 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/py/ReadmeRef_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral, targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral, targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -48,6 +48,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 raises on error.',
   },
+  patch: {
+    sig: 'patch(reqdata, ctrl=None) -> dict',
+    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 raises on error.',
+  },
   remove: {
     sig: 'remove(reqmatch, ctrl=None) -> dict',
     returns: 'the removed entity data',
@@ -216,7 +221,7 @@ ${eVar} = client.${ent.Name}()
         if (hasFieldOps) {
           // Only emit columns for operations this entity actually exposes —
           // never advertise a create/update/remove column the entity lacks.
-          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
 
@@ -256,6 +261,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           // Show example. Entity ops return the ENTITY and raise on
           // error; direct() is the only method that returns a result dict.
           if ('load' === opname || 'remove' === opname) {
@@ -306,10 +315,10 @@ result = client.${ent.Name}().create({
 
 `)
           }
-          else if ('update' === opname) {
+          else if ('update' === opname || 'patch' === opname) {
             // The id key plus every REQUIRED data member — the same shape the
             // runtime validates — then the patch-fields note.
-            const updateItems = opRequestShape(ent, 'update').items
+            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))
@@ -317,13 +326,21 @@ result = client.${ent.Name}().create({
               `    "${it.name}": ${pyLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`python
-result = client.${ent.Name}().update({
-${updateLines}    # Fields to update
+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: '`bytes`, `bytearray`, `memoryview`, a `str` or a file object',
+              once: 'a file object',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/py/ReadmeTopTest_py.ts

@@ -48,7 +48,7 @@ client = ${model.const.Name}SDK.test()
         ? `{${items.map((it: any) =>
           `"${it.name}": ${it.name === idF ? '"test01"' : pyLit(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/py/TestClean_py.ts

@@ -188,7 +188,23 @@ SCENARIOS = [
 ]
 
 
-def _make_sdk(respond, sinks, cleanopts=None, extra=None):
+# Offline, as every generated suite is: the test OPTION resolves a required
+# server variable to test-<name>, and installs no transport.
+def _offline(opts):
+    return dict(opts, test={"active": True})
+
+
+# A client the sweep cannot build leaves nothing swept: a harness error, not a leak.
+def _construct(opts):
+    try:
+        return ${Name}SDK(_offline(opts))
+    except Exception as e:
+        raise RuntimeError(
+            "clean harness: the client could not be constructed, so nothing was swept: "
+            + str(e)) from e
+
+
+def _make_sdk(respond, sinks, cleanopts=None, extra=None, auth=None):
     def capture(name):
         return lambda rec, *a: sinks.extend(_forms(name, rec))
 
@@ -214,7 +230,7 @@ def _make_sdk(respond, sinks, cleanopts=None, extra=None):
     clean = {"values": CANARY["value"]}
     clean.update(cleanopts or {})
 
-    return ${Name}SDK({
+    opts = {
         "apikey": CANARY["apikey"],
         "secret": CANARY["secret"],
         "headers": {"X-Custom-Token": CANARY["header"]},
@@ -222,14 +238,17 @@ def _make_sdk(respond, sinks, cleanopts=None, extra=None):
         "feature": feature,
         "extend": [_CaptureFeature(sinks)] + list(extra or []),
         "utility": {"fetcher": lambda ctx, url, fetchdef: respond(url, fetchdef)},
-    })
+    }
+    if auth is not None:
+        opts["auth"] = auth
+    return _construct(opts)
 
 
 # The first operation that completes against a plain 200: with no
 # arguments, else with every path parameter its points declare filled in.
 def _usable_op():
     def plain():
-        return ${Name}SDK({
+        return _construct({
             "apikey": CANARY["apikey"],
             "utility": {"fetcher": lambda ctx, url, fetchdef: (_response(200, {"id": "i1"}), None)},
         })
@@ -257,7 +276,7 @@ def _usable_op():
     safe = {"list": 0, "load": 1}
     for name in sorted(found):
         accessor, ent = found[name]
-        ops = [op for op in ["list", "load", "create", "update", "remove"]
+        ops = [op for op in ["list", "load", "create", "update", "patch", "remove"]
                if callable(getattr(ent, op, None))]
         ops.sort(key=lambda o: safe.get(o, 2))
         opdefs = (entities.get(name) or {}).get("op") or {}
@@ -338,16 +357,19 @@ class _StreamOkFeature(${Name}BaseFeature):
 def _drive(sdk, target, ctrl, sinks):
     # A caller may keep the record it passed rather than read ctrl["explain"].
     held = ctrl.get("explain")
+    entity = getattr(sdk, target[0])()
     out = None
     err = None
     try:
-        out = getattr(getattr(sdk, target[0])(), target[1])(dict(target[2]), ctrl)
+        out = getattr(entity, target[1])(dict(target[2]), ctrl)
     except Exception as e:
         err = e
     if err is not None:
         sinks.extend(_forms("error", err))
     if out is not None:
         sinks.extend(_forms("result", out))
+    # Raw, as a caller copying the match into another query reads it.
+    sinks.extend(_forms("match", entity.match_get()))
     if ctrl.get("explain") is not None:
         sinks.extend(_forms("explain", ctrl["explain"]))
     if held is not None and held is not ctrl.get("explain"):
@@ -383,11 +405,16 @@ class TestClean:
                 sinks.extend(_forms("sdk", sdk))
                 sinks.append(("sdk:vars", json.dumps(vars(sdk), default=repr)))
 
+        # A name given at run time replaces the declared one: the match
+        # leaves out whichever name prepare_auth placed.
+        _drive(_make_sdk(SCENARIOS[0][1], sinks, auth={"name": "zzcred"}), target, {}, sinks)
+
         # A credential mistyped as a map is rejected by validation, whose
         # message quotes the value it rejected.
         rejected = None
         try:
-            ${Name}SDK({"apikey": {"value": CANARY["apikey"]}, "clean": {"values": CANARY["value"]}})
+            ${Name}SDK(_offline(
+                {"apikey": {"value": CANARY["apikey"]}, "clean": {"values": CANARY["value"]}}))
         except Exception as e:
             rejected = e
         assert rejected is not None, "a credential mistyped as a map should be rejected"
@@ -453,7 +480,7 @@ class TestClean:
         assert cfgclean == {"keys": "zzsens", "values": CANARY["config"]}, cfgclean
 
         # With no clean option at all, the schema defaults still apply.
-        bare = ${Name}SDK({
+        bare = _construct({
             "apikey": CANARY["apikey"],
             "secret": CANARY["secret"],
             "headers": {"X-Custom-Token": CANARY["header"]},
@@ -463,12 +490,14 @@ class TestClean:
 
         # 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.
-        featured = ${Name}SDK({
+        # settings or seeded records keyed by entity name and id, is not read,
+        # and nor are rbac's rules, keyed by entity and operation names.
+        featured = _construct({
             "apikey": CANARY["apikey"],
             "feature": {
                 "zzsecrets": {"active": False, "kind": "PLAINSETTING-q8w2e4r6"},
                 "zzfeat": {"active": False, "apitoken": "FEATTOKEN-z9y8x7w6"},
+                "rbac": {"active": False, "rules": {"zztoken.load": "PLAINRULE-k7j5h3g1"}},
                 "test": {"active": False, "entity": {
                     "zztoken": {"ZZTOKEN01": {"note": "PLAINRECORD-t5r3e1w9"}}}},
             },
@@ -480,6 +509,7 @@ class TestClean:
         ftoken = fclean(froot, "token FEATTOKEN-z9y8x7w6")
         frecord = fclean(froot, "record PLAINRECORD-t5r3e1w9")
         falias = fclean(froot, "alias PLAINALIAS-m2n4b6v8")
+        frule = fclean(froot, "rule PLAINRULE-k7j5h3g1")
 
         leaked = [(name, _leaks(text)) for name, text in sinks]
         leaked = [(name, found) for name, found in leaked if 0 < len(found)]
@@ -513,6 +543,7 @@ class TestClean:
         assert ftoken == "token " + MASK, ftoken
         assert frecord == "record PLAINRECORD-t5r3e1w9", frecord
         assert falias == "alias PLAINALIAS-m2n4b6v8", falias
+        assert frule == "rule PLAINRULE-k7j5h3g1", frule
 
         explained = explains.get("ok/explain") or {}
         assert explained.get("result") is not None, "the explain record should carry the result"