@voxgig/sdkgen 4.34.0 → 4.34.2

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

@@ -1,13 +1,14 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, invalidRequest, opReachable } from '@voxgig/sdkgen'
 
 
 const TestEntity = cmp(function TestEntity(props: any) {
   const e = props.entity
 
-  const ops = Object.keys(e.op || {})
-  const hasCreate = ops.includes('create')
-  const hasList = ops.includes('list')
+  // Each smoke call passes only what it shows, so a bare call must reach a
+  // route: a name for create, nothing for list.
+  const hasCreate = opReachable(e.op?.create, ['name'])
+  const hasList = opReachable(e.op?.list, [])
 
   // Accessor existence.
   Content(`  (t/run-check rec "gen-exists-${e.name}"
@@ -40,7 +41,16 @@ const TestEntity = cmp(function TestEntity(props: any) {
   }
 
   if (hasList) {
-    Content(`  (t/run-check rec "gen-stream-${e.name}"
+    Content(`  (t/run-check rec "gen-list-${e.name}"
+    (fn [] (let [seed (vs/jm "${e.name}" (vs/jm "L1" (vs/jm "id" "L1" "name" "a")
+                                                "L2" (vs/jm "id" "L2" "name" "b")))
+                 items (e-${e.name}/list (api/${e.name} (api/test-sdk (vs/jm "entity" seed) nil) nil)
+                                         (vs/jm) nil)]
+             ;; list resolves to one entity per record; data-get reads the record.
+             (t/is-eq (count items) 2 "list answers each seeded record")
+             (t/is-true (every? (fn [item] (and (map? item) (vs/ismap ((:data-get item))))) items)
+                        "each listed item is an entity carrying its record"))))
+  (t/run-check rec "gen-stream-${e.name}"
     (fn [] (let [seed (vs/jm "${e.name}" (vs/jm "S1" (vs/jm "id" "S1" "name" "a")
                                                 "S2" (vs/jm "id" "S2" "name" "b")
                                                 "S3" (vs/jm "id" "S3" "name" "c")))]
@@ -63,6 +73,55 @@ const TestEntity = cmp(function TestEntity(props: any) {
                      batches (vec (e-${e.name}/stream (api/${e.name} csdk nil) "list" (vs/jm) nil))]
                  (t/is-eq (count batches) 2 "stream chunkSize groups items into 2 batches"))))))
 `)
+
+    // Failure paths: the stream, the caller's ctrl, and a throwing hook.
+    Content(`  (t/run-check rec "gen-stream-error-${e.name}"
+    (fn [] (let [offline (vs/jm "net" (vs/jm "offline" true))
+                 err (try (vec (e-${e.name}/stream (api/${e.name} (api/test-sdk offline nil) nil) "list" (vs/jm) nil)) nil
+                          (catch Throwable e e))]
+             (t/is-true (and (some? err) (.contains (str (.getMessage ^Throwable err)) "offline"))
+                        "the transport failure raises from the stream")
+             (t/is-eq (count (vec (e-${e.name}/stream (api/${e.name} (api/test-sdk offline nil) nil) "list" (vs/jm)
+                                                 (vs/jm "ctrl" (vs/jm "throw" false)))))
+                      0 "throw false ends the stream quietly")
+             (when (vs/getpath (config/make-config) "feature.rbac")
+               (let [denied (api/test-sdk nil (vs/jm "feature" (vs/jm "rbac" (vs/jm "active" true "deny" true))))]
+                 (t/is-throws (fn [] (vec (e-${e.name}/stream (api/${e.name} denied nil) "list" (vs/jm) nil)))
+                              "rbac_denied" "the rbac denial raises from the stream"))))))
+  (t/run-check rec "gen-stream-ctrl-${e.name}"
+    (fn [] (let [explain (vs/jm)
+                 ctrl (vs/jm "explain" explain)]
+             (vec (e-${e.name}/stream (api/${e.name} (api/test-sdk nil nil) nil) "list" (vs/jm) (vs/jm "ctrl" ctrl)))
+             (t/is-eq (vec (vs/keysof ctrl)) ["explain"] "the stream changed the caller's ctrl")
+             (t/is-true (identical? explain (vs/getprop ctrl "explain")) "the caller's explain record is not its own")
+             (t/is-true (pos? (count (vs/keysof explain))) "the caller's explain record was not filled"))))
+  (t/run-check rec "gen-unexpected-${e.name}"
+    (fn [] (let [seen (atom 0)
+                 hook (atom {:name "failhook" :active true :version "0.0.1" :_options nil
+                             "init" (fn [_ctx _opts] nil)
+                             "PreSpec" (fn [_ctx] (throw (RuntimeException. "${e.name} hook failed")))
+                             "PreUnexpected" (fn [_ctx] (swap! seen inc))})
+                 ent (api/${e.name} (api/make-sdk (vs/jm "feature" (vs/jm "test" (vs/jm "active" true)) "extend" [hook])) nil)
+                 err (try (e-${e.name}/list ent (vs/jm) nil) nil (catch Throwable e e))]
+             (t/is-true (and (some? err) (.contains (str (.getMessage ^Throwable err)) "hook failed"))
+                        "the hook's failure is raised")
+             (t/is-true (pos? @seen) "PreUnexpected did not fire")
+             (let [fired @seen]
+               (t/is-nil (e-${e.name}/list ent (vs/jm) (vs/jm "throw" false)) "throw false should resolve to nothing")
+               (t/is-true (> @seen fired) "PreUnexpected did not fire under throw false")))))
+`)
+  }
+
+  const bad = invalidRequest(e)
+  if (null != bad) {
+    const args = Object.entries(bad.args)
+      .map(([k, v]) => JSON.stringify(k) + ' ' + JSON.stringify(v)).join(' ')
+    Content(`  (t/run-check rec "gen-validate-${e.name}"
+    (fn [] (when (vs/getpath (config/make-config) "feature.validate")
+             (let [client (api/test-sdk nil (vs/jm "feature" (vs/jm "validate" (vs/jm "active" true))))]
+               (t/is-throws (fn [] (e-${e.name}/${bad.op} (api/${e.name} client nil) (vs/jm ${args}) nil))
+                            "validate_failed" "validate refuses an invalid request")))))
+`)
   }
 })
 

package/project/.sdk/src/cmp/clojure/fragment/Entity.fragment.clj

@@ -73,6 +73,21 @@
 
 (defn deleted [ent] (true? (deref (:_deleted ent))))
 
+(defn- unexpected
+  "The catch path every entity call leaves through: an error a hook threw,
+  SDK-shaped or not, never passed through make-error. Nil when the caller
+  switched throwing off."
+  [ctx operr]
+  ;; What a hook throws here must not escape the cleaning below.
+  (let [err (try
+              ; #PreUnexpected-Hook
+              operr
+              (catch Throwable hookerr hookerr))]
+    (core/clean-explain! ctx)
+    (let [cleaned (core/clean-throwable ctx err)]
+      (when-not (= false (core/oget (core/oget ctx :ctrl) :throw))
+        (throw cleaned)))))
+
 (defn- run-op [ctx post-done]
   (try
     ; #PrePoint-Hook
@@ -109,15 +124,7 @@
                                   (post-done)
                                   ((core/uget ctx :done) ctx))))))))))))))))
     (catch Throwable operr
-      ;; What a hook throws here must not escape the cleaning below.
-      (let [err (try
-                  ; #PreUnexpected-Hook
-                  operr
-                  (catch Throwable hookerr hookerr))]
-        ;; An error a hook threw, SDK-shaped or not, never passed through
-        ;; make-error.
-        (core/clean-explain! ctx)
-        (throw (core/clean-throwable ctx err))))))
+      (unexpected ctx operr))))
 
 ;; Streaming operation. Runs `action` (an op name, e.g. "list") through the
 ;; full pipeline and returns a LAZY SEQUENCE of result items, so the
@@ -125,7 +132,8 @@
 ;; materialises the whole result). When the streaming feature is active the
 ;; result carries a `stream` thunk and this yields from it (honouring
 ;; chunkSize); otherwise it falls back to the materialised items, so stream
-;; always yields. Records are unwrapped to bare struct maps (matching list).
+;; always yields. An entity is yielded as its record, the struct map its
+;; data-get returns.
 ;; `callopts` parameterises the call:
 ;;   - ctrl:   per-call pipeline control (threaded onto the op ctx);
 ;;   - body:   an async-iterable/list payload for outbound (upload) streaming,
@@ -133,7 +141,9 @@
 ;;   - signal: an optional 0-arg fn; when it returns true iteration stops.
 (defn stream [ent action args callopts]
   (let [callopts (let [m (core/to-map callopts)] (if m m (vs/jm)))
-        ctrl (let [c (core/to-map (vs/getprop callopts "ctrl"))] (if c c (vs/jm)))
+        ;; A copy: the caller's ctrl gains no key, and explain stays its own record.
+        ctrl (let [c (core/to-map (vs/getprop callopts "ctrl"))]
+               (if c (java.util.LinkedHashMap. ^java.util.Map c) (vs/jm)))
         _ (.put ^java.util.Map ctrl "stream" callopts)
         ctxmap (vs/jm "opname" action "ctrl" ctrl
                       "match" (deref (:_match ent)) "data" (deref (:_data ent)))
@@ -167,7 +177,7 @@
                           (vec ((core/oget result :stream)))
                           (let [rd (when result (core/oget result :resdata))]
                             (cond (vs/islist rd) (vec rd) (nil? rd) [] :else [rd]))))
-                  (catch Throwable e (throw (core/clean-throwable ctx e))))]
+                  (catch Throwable e (unexpected ctx e) []))]
       ;; A lazy sequence that checks `signal` between yields.
       (letfn [(lz [xs] (lazy-seq
                          (when (and (seq xs) (not (signalled?)))
@@ -182,4 +192,6 @@
 
 ; #UpdateOp
 
+; #PatchOp
+
 ; #RemoveOp

package/project/.sdk/src/cmp/clojure/fragment/EntityListOp.fragment.clj

@@ -1,17 +1,15 @@
 ; EJECT-START
 ;; List EntityName items matching a filter (reqmatch: any subset of fields).
-;; Yields a bare vector of records (each an accessible map), unwrapping the
-;; entity instances make-result produced for internal use.
+;; Resolves to a vector of entities, one per record, as make-result builds
+;; them; ((:data-get item)) reads an item's record.
 (defn list [ent reqmatch ctrl]
   (let [ctx (core/make-context
              (vs/jm "opname" "list" "ctrl" ctrl
                     "match" (deref (:_match ent)) "data" (deref (:_data ent)) "reqmatch" reqmatch)
              (:_entctx ent))
-        records (run-op ctx
-                        (fn []
-                          (when-let [result (core/oget ctx :result)]
-                            (when (core/oget result :resmatch) (reset! (:_match ent) (core/oget result :resmatch))))))]
-    (if (vs/islist records)
-      (mapv (fn [item] (if (and (map? item) (:data-get item)) ((:data-get item)) item)) (vec records))
-      records)))
+        items (run-op ctx
+                      (fn []
+                        (when-let [result (core/oget ctx :result)]
+                          (when (core/oget result :resmatch) (reset! (:_match ent) (core/oget result :resmatch))))))]
+    (if (vs/islist items) (vec items) items)))
 ; EJECT-END

package/project/.sdk/src/cmp/clojure/fragment/EntityPatchOp.fragment.clj

@@ -0,0 +1,15 @@
+; EJECT-START
+;; Change part of an existing EntityName (reqdata: only the fields to send).
+(defn patch [ent reqdata ctrl]
+  (let [ctx (core/make-context
+             (vs/jm "opname" "patch" "ctrl" ctrl
+                    "match" (deref (:_match ent)) "data" (deref (:_data ent)) "reqdata" reqdata)
+             (:_entctx ent))]
+    (op-return ent ctx (run-op ctx
+            (fn []
+              (when-let [result (core/oget ctx :result)]
+                (when (core/oget result :resmatch) (reset! (:_match ent) (core/oget result :resmatch)))
+                (when (core/oget result :resdata)
+                  (reset! (:_data ent)
+                          (let [m (core/to-map (vs/clone (core/oget result :resdata)))] (if m m (vs/jm)))))))))))
+; EJECT-END

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

@@ -6,6 +6,8 @@ import {
   walk,
 } from '@voxgig/struct'
 
+import { canonScalarKey, requiredItems } from '@voxgig/sdkgen'
+
 
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
@@ -119,7 +121,19 @@ function cljStringChunks(json: string, maxBytes: number = 20000): string[] {
   return 0 === chunks.length ? [''] : chunks
 }
 
+// A list's required route and query parameters, as the match it is called with.
+function cljListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'nil', INTEGER: '1', NUMBER: '1', BOOLEAN: 'true', ARRAY: '(vs/jt)', OBJECT: '(vs/jm)' }) as any)[canonScalarKey(type)] ?? '"example"'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `(vs/jm ${items.map((it: any) => `${cljString(it.name)} ${lit(it.type)}`).join(' ')})`
+    : 'nil'
+}
+
+
 export {
+  cljListMatch,
   cljStringChunks,
   clean,
   formatCljValue,

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

@@ -114,7 +114,7 @@ namespace types {
       })), log)
 
       const ops = ent.op || {}
-      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+      ;['load', 'list', 'create', 'update', 'patch', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {
           return
         }

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

@@ -38,12 +38,12 @@ const Entity = cmp(function Entity(props: any) {
       // For each CRUD op: splice the real method if the spec defines it, else
       // a stub that satisfies the SdkEntity interface but throws at runtime.
       const opfrags =
-        (['load', 'list', 'create', 'update', 'remove']
+        (['load', 'list', 'create', 'update', 'patch', 'remove']
           .reduce((a: any, opname: string) =>
           (a['#' + camelify(opname) + 'Op'] =
             !opnames.includes(opname) ?
               ({ indent }: any) => {
-                const arg = ('create' === opname || 'update' === opname) ?
+                const arg = ('create' === opname || 'update' === opname || 'patch' === opname) ?
                   'reqdata' : 'reqmatch'
                 // The stub mirrors the real signature: ops resolve to the
                 // ENTITY (`list` to a vector of them), so an unsupported op

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

@@ -5,6 +5,7 @@ import {
   cmp, each,
   File, Copy, Folder, Fragment,
   TEST_CONTROL_EXCLUDE,
+  inactiveFeatureExcludes,
   pluginExcludes,
   targetFeatures,
 } from '@voxgig/sdkgen'
@@ -39,22 +40,6 @@ const Main = cmp(async function Main(props: any) {
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
 
   const feature = targetFeatures(model, target)
-  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  const allfeature = getModelPath(model, `main.${KIT}.feature`,
-    { required: false, only_active: false }) || {}
-  const inactivePluginExcludes: RegExp[] = []
-  for (const fname of Object.keys(allfeature)) {
-    if (null != (feature as any)[fname]) continue
-    const groups = getModelPath(model, `main.${KIT}.feature.${fname}.plugin`,
-      { required: false, only_active: false }) || {}
-    for (const gname of Object.keys(groups)) {
-      for (const one of (groups[gname].path || [])) {
-        const pat = esc(String(one))
-        inactivePluginExcludes.push(new RegExp('(^|/)' +
-          pat.replace(/\\\/$/, '') + (/\/$/.test(String(one)) ? '/' : '$')))
-      }
-    }
-  }
 
   Package({ target })
 
@@ -63,7 +48,7 @@ const Main = cmp(async function Main(props: any) {
   Copy({
     from: 'tm/' + target.name,
     exclude: [/src\//, TEST_CONTROL_EXCLUDE,
-      ...pluginExcludes(model), ...inactivePluginExcludes],
+      ...inactiveFeatureExcludes(props.ctx$, target), ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }
@@ -72,8 +57,7 @@ const Main = cmp(async function Main(props: any) {
   // entity/entities.hpp — the entity umbrella (declares every entity header).
   EntityBase({ target })
 
-  // <sdk>_types.hpp — documentation/reference structs (not used by the
-  // Value-based runtime; safe convenience types for consumers).
+  // <sdk>_types.hpp — reference structs for consumers; the runtime ignores them.
   EntityTypes({ target })
 
   Folder({ name: 'core' }, () => {

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

@@ -74,11 +74,14 @@ function render(spec: AuthSpec): string {
 #ifndef SDK_UTILITY_PREPARE_AUTH_HPP
 #define SDK_UTILITY_PREPARE_AUTH_HPP
 
-${withBasic ? `#include <cstddef>
+${'header' === spec.where ? `#include <algorithm>
+` : ''}${withBasic ? `#include <cstddef>
 ` : ''}#include <string>
-
+${'cookie' === spec.where ? `#include <vector>
+` : ''}
 #include "../core/types.hpp"
-
+${'cookie' === spec.where ? `#include "cookie.hpp"
+` : ''}
 namespace sdk {
 namespace util {
 
@@ -150,10 +153,25 @@ inline std::string authBase64(const std::string& in) {
   // Public APIs that need no auth omit the options.auth block entirely, and
   // \`auth: null\` is the documented way to suppress a credential outright.
   if (is_nullish(getp(options, "auth"))) {
-${clear(spec.where, 4)}
+${clear(spec.where, 'CRED_NAME', 4)}
     return spec;
   }
 
+  // The client's auth.name option, when set, replaces the name the API declares.
+  std::string name = as_str(Struct::getpath(options, {"auth", "name"}));
+  if (name.empty()) {
+    name = CRED_NAME;
+  }${'header' === spec.where ? ` else {
+    // ASCII rules, as a field name is ASCII: std::tolower follows the C locale.
+    std::transform(name.begin(), name.end(), name.begin(),
+      [](char c) { return ('A' <= c && c <= 'Z') ? static_cast<char>(c - 'A' + 'a') : c; });
+  }` : ''}
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if (name != CRED_NAME) {
+${clear(spec.where, 'CRED_NAME', 4)}
+  }
+
   Value apikey = getp(options, "apikey", Value(NOT_FOUND));
 
   bool skip = false;
@@ -181,7 +199,7 @@ ${clear(spec.where, 4)}
     }
 
     if (skip) {
-${clear(spec.where, 6)}
+${clear(spec.where, 'name', 6)}
     } else {
       std::string authPrefix = as_str(Struct::getpath(options, {"auth", "prefix"}));
       std::string b64 = authBase64(
@@ -191,9 +209,9 @@ ${clear(spec.where, 6)}
       // registration covers.
       ctx->utility->cleanAdd(ctx, Value(b64));
       if (authPrefix.empty()) {
-        map_put(headers, CRED_NAME, Value(b64));
+        map_put(headers, name, Value(b64));
       } else {
-        map_put(headers, CRED_NAME, Value(authPrefix + " " + b64));
+        map_put(headers, name, Value(authPrefix + " " + b64));
       }
     }
 
@@ -203,7 +221,7 @@ ${clear(spec.where, 6)}
 
   return head + helpers + basicHelper + preamble + basicBlock + `
   if (skip) {
-${clear(spec.where, 4)}
+${clear(spec.where, 'name', 4)}
   } else {
 ${place(spec.where)}
   }
@@ -215,37 +233,18 @@ ${place(spec.where)}
 
 
 function cookieHelpers(): string {
-  return `// The cookie header minus our own pair, every other cookie untouched.
+  return `// The cookie header minus the named pair, every other cookie untouched.
 inline std::string authCookieRest(const Value& headers, const std::string& cred) {
-  std::string existing = as_str(getp(headers, "cookie"));
-  if (existing.empty()) return "";
-
   std::string kept;
-  size_t start = 0;
-  while (start <= existing.size()) {
-    size_t sep = existing.find(';', start);
-    std::string piece = (std::string::npos == sep)
-      ? existing.substr(start) : existing.substr(start, sep - start);
-
-    size_t a = piece.find_first_not_of(" \\t");
-    size_t b = piece.find_last_not_of(" \\t");
-    piece = (std::string::npos == a) ? "" : piece.substr(a, b - a + 1);
-
-    bool ours = piece == cred || 0 == piece.compare(0, cred.size() + 1, cred + "=");
-    if (!piece.empty() && !ours) {
-      if (!kept.empty()) kept += "; ";
-      kept += piece;
-    }
-
-    if (std::string::npos == sep) break;
-    start = sep + 1;
+  for (const auto& cookie : cookieKeep(as_str(getp(headers, "cookie")), std::vector<std::string>{cred})) {
+    if (!kept.empty()) kept += "; ";
+    kept += cookie;
   }
-
   return kept;
 }
 
 
-// Set (remove=false) or drop (remove=true) our pair, leaving the rest in place.
+// Set (remove=false) or drop (remove=true) the named pair, leaving the rest in place.
 inline void authCookieApply(const Value& headers, const std::string& cred,
                             const std::string& value, bool remove) {
   std::string rest = authCookieRest(headers, cred);
@@ -278,24 +277,24 @@ function bagName(where: string): string {
 }
 
 
-function clear(where: string, indent: number): string {
+function clear(where: string, name: string, indent: number): string {
   const pad = ' '.repeat(indent)
 
   if ('cookie' === where) {
-    return `${pad}authCookieApply(headers, CRED_NAME, "", true);`
+    return `${pad}authCookieApply(headers, ${name}, "", true);`
   }
 
-  return `${pad}map_remove(${bagName(where)}, CRED_NAME);`
+  return `${pad}map_remove(${bagName(where)}, ${name});`
 }
 
 
 function place(where: string): string {
   if ('query' === where) {
-    return `    map_put(query, CRED_NAME, Value(apikey.is_string() ? apikey.as_string() : ""));`
+    return `    map_put(query, name, Value(apikey.is_string() ? apikey.as_string() : ""));`
   }
 
   if ('cookie' === where) {
-    return `    authCookieApply(headers, CRED_NAME,
+    return `    authCookieApply(headers, name,
       apikey.is_string() ? apikey.as_string() : "", false);`
   }
 
@@ -304,9 +303,9 @@ function place(where: string): string {
     // A raw credential (empty prefix, e.g. an apiKey scheme) must go in
     // as-is; only a non-empty prefix (Bearer/Basic/OAuth) is space-joined.
     if (authPrefix.empty()) {
-      map_put(headers, CRED_NAME, Value(apikeyVal));
+      map_put(headers, name, Value(apikeyVal));
     } else {
-      map_put(headers, CRED_NAME, Value(authPrefix + " " + apikeyVal));
+      map_put(headers, name, Value(authPrefix + " " + apikeyVal));
     }`
 }
 

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

@@ -1,12 +1,12 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppListMatch } from './utility_cpp'
 
 
 // Type names come from the shared canonToType 'cpp' column (single source of truth).
@@ -14,6 +14,7 @@ import { cppVarName } from './utility_cpp'
 // A type-correct C++ literal for a field's canonical type.
 function cppLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -25,11 +26,12 @@ function cppLit(type: any, placeholder: string = 'example'): string {
 // Operation method spellings for the C++ target: lowercase methods that take a
 // request Value plus the ctrl Value, returning sdk::Value.
 const OP_DESC: Record<string, { method: string, desc: string }> = {
-  load:   { method: 'load(match, ctrl)',   desc: 'Load a single entity by match criteria.' },
-  list:   { method: 'list(match, ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
-  create: { method: 'create(data, ctrl)',  desc: 'Create a new entity with the given data.' },
-  update: { method: 'update(data, ctrl)',  desc: 'Update an existing entity.' },
-  remove: { method: 'remove(match, ctrl)', desc: 'Remove the matching entity.' },
+  load:   { method: 'load(match, ctrl) -> SdkEntityPtr',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(match, ctrl) -> std::vector<SdkEntityPtr>', desc: 'List entities, optionally matching the given criteria: one entity per record.' },
+  create: { method: 'create(data, ctrl) -> SdkEntityPtr',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data, ctrl) -> SdkEntityPtr',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(data, ctrl) -> SdkEntityPtr',  desc: 'Change part of an existing entity.' },
+  remove: { method: 'remove(match, ctrl) -> SdkEntityPtr', desc: 'Remove the matching entity, which is returned marked as deleted.' },
 }
 
 
@@ -54,6 +56,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)
@@ -111,7 +115,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
@@ -126,23 +130,27 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       Content(`#### Example: Load
 
 \`\`\`cpp
-Value ${eVar} = client->${acc}()->load(${loadArg}, Value::undef());
+SdkEntityPtr ${eVar} = client->${acc}()->load(${loadArg}, Value::undef());
+std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`cpp
-Value ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
+std::vector<SdkEntityPtr> ${eVar}s = client->${acc}()->list(${cppListMatch(entity)}, Value::undef());
+for (const auto& ${eVar} : ${eVar}s) {
+  std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
+}
 \`\`\`
 
 `)
     }
 
-    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
@@ -150,7 +158,7 @@ Value ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
       Content(`#### Example: Create
 
 \`\`\`cpp
-Value ${eVar} = client->${acc}()->create(vmap({
+SdkEntityPtr ${eVar} = client->${acc}()->create(vmap({
 `)
       createItems.map((it: any) => {
         Content(`    {"${it.name}", ${cppLit(it.type, 'example_' + it.name)}},  // ${canonToType(it.type, target.name)}

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

@@ -1,17 +1,18 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cppVarName } from './utility_cpp'
+import { cppVarName, cppEscape } from './utility_cpp'
 
 
 // A type-correct C++ literal for a field's canonical type.
 function cppLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value(nullptr)'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
   if ('BOOLEAN' === k) return 'Value(true)'
   if ('ARRAY' === k) return 'vlist()'
@@ -36,21 +37,29 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'Value::undef()'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `vmap({{"${idF}", Value("test01")}})` : 'Value::undef()'
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `vmap({${chosen.map((it: any) => `{"${cppEscape(it.name)}", ${cppLit(it.type)}}`).join(', ')}})`
+  } 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)
     const chosen = required.length ? required : items.slice(0, 3)
-    testArg = `vmap({${chosen.map((it: any) => `{"${it.name}", ${cppLit(it.type)}}`).join(', ')}})`
+    testArg = `vmap({${chosen.map((it: any) => `{"${cppEscape(it.name)}", ${cppLit(it.type)}}`).join(', ')}})`
   }
 
   // The op-driven test-mode line, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
-  const testModeExample = primaryOp
-    ? `// Entity ops return the bare record and throw on error.
-Value ${eVar} = client->${acc}()->${primaryOp}(${testArg}, Value::undef());
-// ${eVar} contains the mock response record
-std::cout << Struct::jsonify(${eVar}) << std::endl;`
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns one entity per mock record, and throws on error.
+for (const auto& ${eVar} : client->${acc}()->list(${testArg}, Value::undef())) {
+  std::cout << Struct::jsonify(${eVar}->data()) << std::endl;
+}`
+    : primaryOp
+    ? `// Entity ops return the entity and throw on error.
+SdkEntityPtr ${eVar} = client->${acc}()->${primaryOp}(${testArg}, Value::undef());
+// ${eVar}->data() is the mock response record
+std::cout << Struct::jsonify(${eVar}->data()) << std::endl;`
     : `Value result = client->direct(vmap({
     {"path", Value("/api/resource")},
     {"method", Value("GET")},

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

@@ -10,13 +10,13 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   // Consumers vendor the source tree (or add it as a submodule) and put the
   // SDK directory on the compiler include path. The git release tag
   // (`cpp/vX.Y.Z`) is the unit of distribution.
-  const { releasesUrl } = repoInfo(model)
+  const { tagsUrl } = repoInfo(model)
 
   Content(`The ${target.title} SDK is **header-only** — there is no package to install
 from a registry. Vendor the \`cpp/\` directory into your project (or add the
 repository as a git submodule) and put it on your compiler's include path.
 Releases are cut as the git tag \`${target.name}/vX.Y.Z\` (see
-[Releases](${releasesUrl})).
+[Tags](${tagsUrl})).
 
 \`\`\`bash
 # Add the SDK as a submodule (or copy the cpp/ directory into your tree).