@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/src/cmp/clojure/PrepareAuth_clojure.ts

@@ -78,7 +78,7 @@ function renderHeader(spec: AuthSpec, head: string): string {
 (def OPTION-APIKEY "apikey")
 ` + (spec.basic ? `(def OPTION-SECRET "secret")
 ` : '') + `(def NOT-FOUND "__NOTFOUND__")
-
+${authName('HEADER-AUTH', true)}
 (defn u-prepare-auth [ctx]
   (let [spec (oget ctx :spec)]
     (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
@@ -87,7 +87,10 @@ function renderHeader(spec: AuthSpec, head: string): string {
           (if (nil? (vs/getprop options "auth"))
             ;; Public APIs that need no auth omit the options.auth block entirely.
             (do (vs/delprop headers HEADER-AUTH) [spec nil])
-            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+            (let [cred (prepare-auth-name options)
+                  apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              ;; A credential left under the declared name would travel beside the renamed one.
+              (when (not= cred HEADER-AUTH) (vs/delprop headers HEADER-AUTH))
 ${spec.basic ? basicBlock() : headerPlace(14)}
               [spec nil]))))))
 `
@@ -97,10 +100,10 @@ ${spec.basic ? basicBlock() : headerPlace(14)}
 function headerPlace(col: number): string {
   const p = ' '.repeat(col)
   return `${p}(if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
-${p}  (vs/delprop headers HEADER-AUTH)
+${p}  (vs/delprop headers cred)
 ${p}  (let [auth-prefix (or (vs/getpath options "auth.prefix") "")
 ${p}        apikey-val (if (string? apikey) apikey "")]
-${p}    (.put ^java.util.Map headers HEADER-AUTH
+${p}    (.put ^java.util.Map headers cred
 ${p}          (if (= auth-prefix "") apikey-val (str auth-prefix " " apikey-val)))))`
 }
 
@@ -117,14 +120,14 @@ function basicBlock(): string {
                       missing? (fn [v] (or (nil? v)
                                            (and (string? v) (or (= v NOT-FOUND) (= v "")))))]
                   (if (missing? apikey)
-                    (vs/delprop headers HEADER-AUTH)
+                    (vs/delprop headers cred)
                     (let [auth-prefix (or (vs/getpath options "auth.prefix") "")
                           b64 (.encodeToString (java.util.Base64/getEncoder)
                                                (.getBytes ^String (str apikey ":" (if (missing? secret) "" secret)) "UTF-8"))]
                       ;; The joined, encoded pair is a wire form neither
                       ;; credential's own registration covers.
                       (ucall ctx :clean-add b64)
-                      (.put ^java.util.Map headers HEADER-AUTH
+                      (.put ^java.util.Map headers cred
                             (if (= auth-prefix "") b64 (str auth-prefix " " b64))))))
 ${headerPlace(16)})`
 }
@@ -137,7 +140,7 @@ function renderQuery(spec: AuthSpec, head: string): string {
 (def QUERY-AUTH ${cljstr(spec.name)})
 (def OPTION-APIKEY "apikey")
 (def NOT-FOUND "__NOTFOUND__")
-
+${authName('QUERY-AUTH', false)}
 (defn u-prepare-auth [ctx]
   (let [spec (oget ctx :spec)]
     (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
@@ -146,14 +149,17 @@ function renderQuery(spec: AuthSpec, head: string): string {
           (if (nil? (vs/getprop options "auth"))
             ;; Public APIs that need no auth omit the options.auth block entirely.
             (do (vs/delprop query QUERY-AUTH) [spec nil])
-            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+            (let [cred (prepare-auth-name options)
+                  apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              ;; A credential left under the declared name would travel beside the renamed one.
+              (when (not= cred QUERY-AUTH) (vs/delprop query QUERY-AUTH))
               (if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
-                (vs/delprop query QUERY-AUTH)
+                (vs/delprop query cred)
                 (let [apikey-val (if (string? apikey) apikey "")]
                   ;; 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.
-                  (.put ^java.util.Map query QUERY-AUTH apikey-val)))
+                  (.put ^java.util.Map query cred apikey-val)))
               [spec nil]))))))
 `
 }
@@ -167,27 +173,22 @@ function renderCookie(spec: AuthSpec, head: string): string {
 (def COOKIE-AUTH ${cljstr(spec.name)})
 (def OPTION-APIKEY "apikey")
 (def NOT-FOUND "__NOTFOUND__")
-
-;; The cookie header minus our own pair, every other cookie left untouched.
-(defn- cookies-without-cred [headers]
+${authName('COOKIE-AUTH', false)}
+;; The cookie header minus the named pair, every other cookie left untouched.
+(defn- cookies-without-cred [headers cred]
   (let [existing (vs/getprop headers HEADER-COOKIE)]
     (if (or (not (string? existing)) (= "" existing))
       ""
-      (str/join "; "
-                (remove (fn [piece]
-                          (or (= "" piece)
-                              (= COOKIE-AUTH piece)
-                              (str/starts-with? piece (str COOKIE-AUTH "="))))
-                        (map str/trim (str/split existing #";")))))))
-
-;; Set (a string) or remove (nil) our pair, leaving the rest in place.
-(defn- apply-cookie! [headers value]
-  (let [rest (cookies-without-cred headers)]
+      (str/join "; " (cookie-keep existing #{cred})))))
+
+;; Set (a string) or remove (nil) the named pair, leaving the rest in place.
+(defn- apply-cookie! [headers cred value]
+  (let [rest (cookies-without-cred headers cred)]
     (if (nil? value)
       (if (= "" rest)
         (vs/delprop headers HEADER-COOKIE)
         (.put ^java.util.Map headers HEADER-COOKIE rest))
-      (let [pair (str COOKIE-AUTH "=" value)]
+      (let [pair (str cred "=" value)]
         (.put ^java.util.Map headers HEADER-COOKIE
               (if (= "" rest) pair (str rest "; " pair)))))))
 
@@ -198,13 +199,16 @@ function renderCookie(spec: AuthSpec, head: string): string {
               options (client-options-map (oget ctx :client))]
           (if (nil? (vs/getprop options "auth"))
             ;; Public APIs that need no auth omit the options.auth block entirely.
-            (do (apply-cookie! headers nil) [spec nil])
-            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+            (do (apply-cookie! headers COOKIE-AUTH nil) [spec nil])
+            (let [cred (prepare-auth-name options)
+                  apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              ;; A credential left under the declared name would travel beside the renamed one.
+              (when (not= cred COOKIE-AUTH) (apply-cookie! headers COOKIE-AUTH nil))
               (if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
-                (apply-cookie! headers nil)
+                (apply-cookie! headers cred nil)
                 ;; NO PREFIX IN A COOKIE either - a cookie carries a bare
                 ;; \`name=value\` pair, not a header's scheme-prefixed credential.
-                (apply-cookie! headers (if (string? apikey) apikey "")))
+                (apply-cookie! headers cred (if (string? apikey) apikey "")))
               [spec nil]))))))
 `
 }
@@ -232,6 +236,18 @@ function renderInactive(spec: AuthSpec, head: string): string {
 }
 
 
+// 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 `
+;; The client's auth.name option, when set, replaces the name the API declares.
+(defn- prepare-auth-name [options]
+  (let [given (vs/getpath options "auth.name")]
+    (if (and (string? given) (not= "" given)) ${header ? '(.toLowerCase ^String given java.util.Locale/ROOT)' : 'given'} ${declared})))
+`
+}
+
+
 function authSwitchedOn(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })

package/project/.sdk/src/cmp/clojure/ReadmeEntity_clojure.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,
@@ -40,6 +40,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: '(list ent match ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
   create: { method: '(create ent data ctrl)',  desc: 'Create a new entity with the given data.' },
   update: { method: '(update ent data ctrl)',  desc: 'Update an existing entity.' },
+  patch:  { method: '(patch ent data ctrl)',   desc: 'Change part of an existing entity.' },
   remove: { method: '(remove ent match ctrl)', desc: 'Remove the matching entity.' },
 }
 
@@ -65,6 +66,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)
@@ -120,7 +123,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.
       const loadItems = opRequestShape(entity, 'load').items
@@ -141,7 +144,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`clojure
@@ -151,7 +154,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear.
       const createItems = opRequestShape(entity, 'create').items

package/project/.sdk/src/cmp/clojure/ReadmeHowto_clojure.ts

@@ -32,7 +32,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'nil'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `(vs/jm "${idF}" "test01")` : 'nil'
-  } 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/clojure/ReadmeInstall_clojure.ts

@@ -5,7 +5,7 @@ import { cmp, Content, isPublished, repoInfo } from '@voxgig/sdkgen'
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
-  const { origin, repo, repoUrl, releasesUrl } = repoInfo(model)
+  const { hostName, origin, repo, repoUrl, tagsUrl } = repoInfo(model)
 
   if (isPublished(model, target.name)) {
     // Live on Clojars: add the published coordinate to deps.edn.
@@ -21,9 +21,9 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   }
 
   // Publish pending: not yet on Clojars. Depend on the library directly from
-  // the GitHub release tag, or from a local checkout via :local/root.
+  // the release tag, or from a local checkout via :local/root.
   Content(`This package is not yet published to Clojars. Depend on it directly from the
-GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})),
+${hostName} release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})),
 using a \`tools.deps\` git dependency:
 
 \`\`\`clojure

package/project/.sdk/src/cmp/clojure/ReadmeIntro_clojure.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -9,7 +9,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 @@ the vendored \`voxgig.struct\` value model).
   // 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/clojure/ReadmeModel_clojure.ts

@@ -21,12 +21,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` | `(ent reqmatch ctrl) -> map` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `list` | `(ent reqmatch ctrl) -> vector` | List entities matching the criteria. Raises on error. |',
+    list: '| `list` | `(ent reqmatch ctrl) -> vector` | List entities matching the criteria. Resolves to one entity per record. Raises on error. |',
     create: '| `create` | `(ent reqdata ctrl) -> map` | Create a new entity. Raises on error. |',
     update: '| `update` | `(ent reqdata ctrl) -> map` | Update an existing entity. Raises on error. |',
+    patch: '| `patch` | `(ent reqdata ctrl) -> map` | Change part of an existing entity. Raises on error. |',
     remove: '| `remove` | `(ent reqmatch ctrl) -> map` | 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)
@@ -99,9 +100,10 @@ State accessors are called by looking up the fn and applying it, e.g.
 
 ### Result shape
 
-Entity operations return the bare result data (a \`map\` for single-entity
-ops, a \`vector\` for \`list\`) and raise (via \`ex-info\`) on error. Wrap
-calls in \`try\`/\`catch\` to handle failures.
+Entity operations resolve to the entity, and \`list\` to a \`vector\` of
+entities, one per record. Read an entity's record with
+\`((:data-get ent))\`. They raise (via \`ex-info\`) on error, so wrap calls
+in \`try\`/\`catch\` to handle failures.
 
 The \`direct\` escape hatch never raises — it returns a result \`map\` you
 branch on via \`(vs/getprop result "ok")\`:

package/project/.sdk/src/cmp/clojure/ReadmeQuick_clojure.ts

@@ -72,13 +72,13 @@ ${requireLines.join('\n')}
     if (opnames.includes('list')) {
       Content(`### 2. List ${eLow} records
 
-\`list\` returns a vector of records (each a map) and raises on error —
-iterate it directly.
+\`list\` returns a vector of entities, one per record, and raises on error.
+Read each record with \`((:data-get ${eLow}))\`.
 
 \`\`\`clojure
 (try
   (doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) nil nil)]
-    (println ${eLow}))
+    (println ((:data-get ${eLow}))))
   (catch Exception err
     (println "list failed:" (.getMessage err))))
 \`\`\`
@@ -166,7 +166,8 @@ ${nestedEntity.Name} is nested under ${parentName}, so provide the
       ? `(vs/getprop created "${dataIdF}")`
       : cljLit(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
 
 \`\`\`clojure
@@ -183,6 +184,13 @@ ${nestedEntity.Name} is nested under ${parentName}, so provide the
         Content(`;; Update${fromCreated ? " — the created record's id is a plain map key" : ''}
 (e-${eLow}/update (api/${eLow} client nil) (vs/jm ${updatePairs.join(' ')}) nil)
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`"${idF}" ${idValueFor('patch')}`] : []).concat(examplePairs('patch'))
+        Content(`;; Patch — sends only the fields given
+(e-${eLow}/patch (api/${eLow} client nil) (vs/jm ${patchPairs.join(' ')}) nil)
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/clojure/ReadmeRef_clojure.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 {
@@ -53,6 +53,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 ent reqdata ctrl) -> map',
+    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 ent reqmatch ctrl) -> map',
     returns: 'the removed entity data',
@@ -221,7 +226,7 @@ Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises
         // 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
 
@@ -262,6 +267,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)
@@ -281,7 +290,7 @@ ${info.desc}
           else if ('list' === opname) {
             Content(`\`\`\`clojure
 (doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) nil nil)]
-  (println ${eLow}))
+  (println ((:data-get ${eLow}))))
 \`\`\`
 
 `)
@@ -304,8 +313,8 @@ ${info.desc}
 
 `)
           }
-          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))
@@ -314,15 +323,23 @@ ${info.desc}
                 it.name === idF ? ent.name + '_id' : it.name)}\n`).join('')
             Content(`\`\`\`clojure
 (def result
-  (e-${eLow}/update (api/${eLow} client nil)
+  (e-${eLow}/${opname} (api/${eLow} client nil)
     (vs/jm
-${updateLines}      ;; Fields to update
+${updateLines}      ;; ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
       )
     nil))
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a byte array, a `String` or an `InputStream`',
+              once: 'an `InputStream`',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/clojure/ReadmeTopQuick_clojure.ts

@@ -51,9 +51,9 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`;; List all ${eLow}s (returns a vector, raises on error)
+      Content(`;; List all ${eLow}s (a vector of entities, one per record; raises on error)
 (doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) nil nil)]
-  (println ${eLow}))
+  (println ((:data-get ${eLow}))))
 `)
     }
 

package/project/.sdk/src/cmp/clojure/ReadmeTopTest_clojure.ts

@@ -54,7 +54,7 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
         ? `(vs/jm ${items.map((it: any) =>
           `"${it.name}" ${it.name === idF ? '"test01"' : cljLit(it.type)}`).join(' ')})`
         : 'nil'
-    } 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/clojure/TestClean_clojure.ts

@@ -28,7 +28,7 @@ const TestClean = cmp(function TestClean(props: any) {
 
 
 const OP_ORDER: Record<string, number> = { list: 0, load: 1 }
-const OPS = ['list', 'load', 'create', 'update', 'remove']
+const OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
 
 
 // The path parameters an operation's points declare, as the runtime config
@@ -182,7 +182,23 @@ function render(model: any, entity: any[], auth: {
                                     "body" "<html>"
                                     "json" (fn [] (throw (RuntimeException. "Unexpected token < in JSON")))) nil])}])
 
-(defn- make-sdk [scenario sinks cleanopts & extra]
+;; Offline, as every generated suite is: the test OPTION resolves a required
+;; server variable to test-<name>, and installs no transport.
+(defn- offline [opts]
+  (.put ^java.util.Map opts "test" (vs/jm "active" true))
+  opts)
+
+;; A client the sweep cannot build leaves nothing swept: a harness error, not
+;; a leak.
+(defn- construct [opts]
+  (try (api/make-sdk (offline opts))
+       (catch Throwable e
+         (throw (IllegalStateException.
+                 (str "clean harness: the client could not be constructed, so nothing was swept: "
+                      (.getMessage e))
+                 e)))))
+
+(defn- sdk-opts [scenario sinks cleanopts extra]
   (let [capture (fn [name] (fn [rec] (swap! sinks into (forms name rec))))
         feature (vs/jm)
         on (fn [name & kvs] (when (feature/feature-present? name)
@@ -196,12 +212,15 @@ function render(model: any, entity: any[], auth: {
     (on "clienttrack")
     (let [clean (vs/jm "values" (:value CANARY))]
       (doseq [[k v] (or cleanopts {})] (.put ^java.util.Map clean k v))
-      (api/make-sdk (vs/jm "apikey" (:apikey CANARY) "secret" (:secret CANARY)
-                           "headers" (vs/jm "X-Custom-Token" (:header CANARY))
-                           "clean" clean
-                           "feature" feature
-                           "extend" (apply vs/jt (capture-feature sinks) extra)
-                           "utility" (vs/jm "fetcher" (fn [_fctx url fd] ((:respond scenario) url fd))))))))
+      (vs/jm "apikey" (:apikey CANARY) "secret" (:secret CANARY)
+             "headers" (vs/jm "X-Custom-Token" (:header CANARY))
+             "clean" clean
+             "feature" feature
+             "extend" (apply vs/jt (capture-feature sinks) extra)
+             "utility" (vs/jm "fetcher" (fn [_fctx url fd] ((:respond scenario) url fd)))))))
+
+(defn- make-sdk [scenario sinks cleanopts & extra]
+  (construct (sdk-opts scenario sinks cleanopts extra)))
 
 ;; A fresh struct map of the match, since an operation may keep what it is
 ;; given.
@@ -219,8 +238,8 @@ ${candidates(entity)}
 ;; The first operation that completes against a plain 200: with no
 ;; arguments, else with every path parameter its points declare filled in.
 (defn- usable-op []
-  (let [plain (api/make-sdk (vs/jm "apikey" (:apikey CANARY)
-                                   "utility" (vs/jm "fetcher" (fn [_ _ _] [(response 200 (vs/jm "id" "i1") {}) nil]))))]
+  (let [plain (construct (vs/jm "apikey" (:apikey CANARY)
+                                "utility" (vs/jm "fetcher" (fn [_ _ _] [(response 200 (vs/jm "id" "i1") {}) nil]))))]
     (some (fn [c]
             (some (fn [match]
                     (try ((:op c) ((:accessor c) plain) match (vs/jm))
@@ -278,6 +297,8 @@ ${candidates(entity)}
         explain (vs/getprop ctrl "explain")]
     (when err (swap! sinks into (forms "error" err)))
     (when (some? out) (swap! sinks into (forms "result" out)))
+    ;; Raw, as a caller copying the match into another query reads it.
+    (swap! sinks into (forms "match" ((:match-get ent))))
     (when (some? explain) (swap! sinks into (forms "explain" explain)))
     (when (and (some? held) (not (identical? held explain))) (swap! sinks into (forms "explain:held" held)))
     err))
@@ -301,10 +322,15 @@ ${candidates(entity)}
               (when-let [ex (vs/getprop ctrl "explain")] (swap! explains assoc key ex))
               (swap! sinks into (forms "sdk" sdk))
               (swap! sinks conj {:name "sdk:slots" :text (pr-str (into {} sdk))})))
+          ;; A name given at run time replaces the declared one: the match
+          ;; leaves out whichever name prepare-auth placed.
+          (let [opts (sdk-opts (first SCENARIOS) sinks nil nil)]
+            (.put ^java.util.Map opts "auth" (vs/jm "name" "zzcred"))
+            (drive (construct opts) target (vs/jm) sinks))
           ;; A credential mistyped as a map is rejected by validation, whose
           ;; message quotes the value it rejected.
-          (let [rejected (try (api/make-sdk (vs/jm "apikey" (vs/jm "value" (:apikey CANARY))
-                                                   "clean" (vs/jm "values" (:value CANARY))))
+          (let [rejected (try (api/make-sdk (offline (vs/jm "apikey" (vs/jm "value" (:apikey CANARY))
+                                                            "clean" (vs/jm "values" (:value CANARY)))))
                               nil
                               (catch Throwable e e))]
             (t/is-some rejected "a credential mistyped as a map should be rejected")
@@ -352,25 +378,28 @@ ${candidates(entity)}
             (t/is-deep (vs/getpath config "options.clean") (vs/jm "keys" "zzsens" "values" (:config CANARY))
                        "the config's clean block is unchanged"))
           ;; With no clean option at all, the schema defaults still apply.
-          (let [bare (api/make-sdk (vs/jm "apikey" (:apikey CANARY) "secret" (:secret CANARY)
-                                          "headers" (vs/jm "X-Custom-Token" (:header CANARY))
-                                          "utility" (vs/jm "fetcher" (fn [_fctx url fd]
-                                                                       ((:respond (nth SCENARIOS 1)) url fd)))))]
+          (let [bare (construct (vs/jm "apikey" (:apikey CANARY) "secret" (:secret CANARY)
+                                       "headers" (vs/jm "X-Custom-Token" (:header CANARY))
+                                       "utility" (vs/jm "fetcher" (fn [_fctx url fd]
+                                                                    ((:respond (nth SCENARIOS 1)) url fd)))))]
             (t/is-some (drive bare target (vs/jm "explain" (vs/jm)) sinks) "the 404 should fail without a clean option"))
           ;; A feature's name is not a field name: only the sensitive names
           ;; inside its settings register. An entity block, of entity settings
-          ;; or seeded records keyed by entity name and id, is not read at all.
+          ;; or seeded records keyed by entity name and id, is not read at all,
+          ;; and nor are rbac's rules, keyed by entity and operation names.
           (let [record (vs/jm "zztoken" (vs/jm "ZZTOKEN01" (vs/jm "note" "PLAINRECORD-t5r3e1w9")))
-                sdk (api/make-sdk (vs/jm "apikey" (:apikey CANARY)
-                                         "feature" (vs/jm "zzsecrets" (vs/jm "active" false "kind" "PLAINSETTING-q8w2e4r6")
-                                                          "zzfeat" (vs/jm "active" false "apitoken" "FEATTOKEN-z9y8x7w6")
-                                                          "test" (vs/jm "active" false "entity" record))
-                                         "entity" (vs/jm "zztoken" (vs/jm "alias" (vs/jm "zzkey" "PLAINALIAS-m2n4b6v8")))))
+                sdk (construct (vs/jm "apikey" (:apikey CANARY)
+                                      "feature" (vs/jm "zzsecrets" (vs/jm "active" false "kind" "PLAINSETTING-q8w2e4r6")
+                                                       "zzfeat" (vs/jm "active" false "apitoken" "FEATTOKEN-z9y8x7w6")
+                                                       "rbac" (vs/jm "active" false "rules" (vs/jm "zztoken.load" "PLAINRULE-k7j5h3g1"))
+                                                       "test" (vs/jm "active" false "entity" record))
+                                      "entity" (vs/jm "zztoken" (vs/jm "alias" (vs/jm "zzkey" "PLAINALIAS-m2n4b6v8")))))
                 root (core/client-root-ctx sdk)]
             (reset! featured {:plain (core/u-clean root "kind PLAINSETTING-q8w2e4r6")
                               :token (core/u-clean root "token FEATTOKEN-z9y8x7w6")
                               :record (core/u-clean root "record PLAINRECORD-t5r3e1w9")
-                              :alias (core/u-clean root "alias PLAINALIAS-m2n4b6v8")}))
+                              :alias (core/u-clean root "alias PLAINALIAS-m2n4b6v8")
+                              :rule (core/u-clean root "rule PLAINRULE-k7j5h3g1")}))
           (let [leaked (filterv (fn [s] (seq (leaks (:text s)))) @sinks)]
             (println (str "clean: swept " (count @sinks) " surface(s), " (count leaked) " leak(s)"))
             (t/is-eq (count leaked) 0
@@ -407,6 +436,7 @@ ${candidates(entity)}
           (t/is-eq (:token @featured) (str "token " MASK) "a sensitive setting inside a feature registers")
           (t/is-eq (:record @featured) "record PLAINRECORD-t5r3e1w9" "a seeded record does not register")
           (t/is-eq (:alias @featured) "alias PLAINALIAS-m2n4b6v8" "an entity setting does not register")
+          (t/is-eq (:rule @featured) "rule PLAINRULE-k7j5h3g1" "an rbac rule keyed by entity and operation does not register")
           (let [explained (get @explains "ok/explain")
                 result (vs/getprop explained "result")]
             (t/is-some result "the explain record should carry the result")