@voxgig/sdkgen 4.34.0 → 4.34.1

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

@@ -1,4 +1,4 @@
-import { flowSteps } from '@voxgig/sdkgen'
+import { flowSteps, invalidRequest, opReachable } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -151,10 +151,10 @@ static void ${evar}_entity_instance() {
 
 `)
 
-    // The stream test drives the list op; only emit it when the entity has a
-    // list op (a create/load-only entity has no list endpoint, so
-    // stream("list") throws "Operation \"list\" has no endpoint definitions").
-    const flowHasList = allSteps.some((s: any) => 'list' === s.o)
+    // The stream test drives the list op with no match; only emit it when a
+    // bare call can reach a list route (see helpers/opShape opReachable).
+    const flowHasList = allSteps.some((s: any) => 'list' === s.o) &&
+      opReachable((entity.op as any)?.list, [])
     if (flowHasList) {
       Content(`
 static void ${evar}_entity_stream() {
@@ -181,6 +181,10 @@ static void ${evar}_entity_stream() {
 `)
     }
 
+    const hasList = opReachable((entity.op as any)?.list, [])
+    const failure = failureTests(ProjectName, entity, evar, method, hasList)
+    Content(failure.code)
+
     Content(`
 static void ${evar}_entity_basic() {
   auto setup = ${evar}_basic_setup(Value::undef());
@@ -224,7 +228,7 @@ static void ${evar}_entity_basic() {
 
 int main() {
   T_RUN(${evar}_entity_instance);
-${flowHasList ? `  T_RUN(${evar}_entity_stream);\n` : ''}  T_RUN(${evar}_entity_basic);
+${flowHasList ? `  T_RUN(${evar}_entity_stream);\n` : ''}${failure.tests.map((t) => `  T_RUN(${t});\n`).join('')}  T_RUN(${evar}_entity_basic);
   return sdktest::summary("${entity.name}_entity_test");
 }
 `)
@@ -232,6 +236,131 @@ ${flowHasList ? `  T_RUN(${evar}_entity_stream);\n` : ''}  T_RUN(${evar}_entity_
 })
 
 
+// Failure paths through the real entity code: a failed or denied operation
+// fails its stream, stream() leaves the caller's ctrl alone, a throwing hook
+// fires PreUnexpected (throw false too), and validate refuses a bad request.
+function failureTests(ProjectName: string, entity: ModelEntity, evar: string,
+  method: string, hasList: boolean): { code: string, tests: string[] } {
+  const tests: string[] = []
+  const bad = invalidRequest(entity)
+  if (!hasList && null == bad) {
+    return { code: '', tests }
+  }
+
+  let code = `
+static bool ${evar}_has_feature(const std::string& name) {
+  Value fm = Helpers::toMapAny(getp(sharedConfig(), "feature"));
+  return fm.is_map() && !getp(fm, name).is_undef();
+}
+`
+
+  if (hasList) {
+    tests.push(`${evar}_entity_stream_error`, `${evar}_entity_stream_ctrl`,
+      `${evar}_entity_unexpected`)
+    code += `
+class ${entity.Name}FailHook : public BaseFeature {
+public:
+  int unexpected = 0;
+  ${entity.Name}FailHook() : BaseFeature("failhook", "0.0.1", true) {}
+  void preSpec(CtxPtr ctx) override {
+    throw std::runtime_error("${entity.name} hook failed");
+  }
+  void preUnexpected(CtxPtr ctx) override {
+    unexpected++;
+  }
+};
+
+static void ${evar}_entity_stream_error() {
+  Value offline = vmap({{"net", vmap({{"offline", Value(true)}})}});
+  std::string msg;
+  try {
+    ${ProjectName}SDK::testSDK(offline, Value::undef())->${method}()
+        ->stream("list", Value::undef(), Value::undef());
+  } catch (const SdkErrorPtr& err) {
+    msg = err->getMessage();
+  }
+  ASSERT_TRUE(msg.find("offline") != std::string::npos,
+      "stream: a failed operation fails the stream");
+
+  bool raised = false;
+  try {
+    ${ProjectName}SDK::testSDK(offline, Value::undef())->${method}()
+        ->stream("list", Value::undef(), vmap({{"ctrl", vmap({{"throw", Value(false)}})}}));
+  } catch (const SdkErrorPtr&) {
+    raised = true;
+  }
+  ASSERT_FALSE(raised, "stream: under throw false a failed stream ends");
+
+  if (${evar}_has_feature("rbac")) {
+    std::string code;
+    try {
+      ${ProjectName}SDK::testSDK(Value::undef(), vmap({{"feature", vmap({{"rbac",
+          vmap({{"active", Value(true)}, {"deny", Value(true)}})}})}}))->${method}()
+          ->stream("list", Value::undef(), Value::undef());
+    } catch (const SdkErrorPtr& err) {
+      code = err->code;
+    }
+    ASSERT_EQ(code, std::string("rbac_denied"), "stream: a denied operation fails the stream");
+  }
+}
+
+static void ${evar}_entity_stream_ctrl() {
+  Value explain = vmap();
+  Value ctrl = vmap({{"explain", explain}});
+  ${ProjectName}SDK::testSDK()->${method}()->stream("list", Value::undef(), vmap({{"ctrl", ctrl}}));
+  ASSERT_TRUE(getp(ctrl, "stream").is_undef(), "stream: the caller's ctrl gains no key");
+  ASSERT_TRUE(!explain.as_map()->empty(), "stream: the caller's explain record is filled");
+}
+
+static void ${evar}_entity_unexpected() {
+  auto hook = std::make_shared<${entity.Name}FailHook>();
+  auto client = ${ProjectName}SDK::testSDK();
+  client->getRootCtx()->utility->featureAdd(client->getRootCtx(), hook);
+
+  std::string msg;
+  try {
+    client->${method}()->list(Value::undef(), Value::undef());
+  } catch (const SdkErrorPtr& err) {
+    msg = err->getMessage();
+  }
+  ASSERT_TRUE(msg.find("hook failed") != std::string::npos, "a throwing hook fails the operation");
+  ASSERT_TRUE(0 < hook->unexpected, "a throwing hook fires PreUnexpected");
+
+  int fired = hook->unexpected;
+  client->${method}()->list(Value::undef(), vmap({{"throw", Value(false)}}));
+  ASSERT_TRUE(fired < hook->unexpected, "under throw false PreUnexpected fires too");
+}
+`
+  }
+
+  if (null != bad) {
+    tests.push(`${evar}_entity_validate`)
+    const args = Object.entries(bad.args)
+      .map(([k, v]) => `{${JSON.stringify(k)}, Value(${JSON.stringify(v)})}`)
+      .join(', ')
+    code += `
+static void ${evar}_entity_validate() {
+  if (!${evar}_has_feature("validate")) {
+    std::cerr << "skip: feature not present in this SDK: validate\\n";
+    return;
+  }
+  auto vsdk = ${ProjectName}SDK::testSDK(Value::undef(), vmap({{"feature",
+      vmap({{"validate", vmap({{"active", Value(true)}})}})}}));
+  std::string code;
+  try {
+    vsdk->${method}()->${bad.op}(vmap({${args}}), Value::undef());
+  } catch (const SdkErrorPtr& err) {
+    code = err->code;
+  }
+  ASSERT_EQ(code, std::string("validate_failed"), "an invalid request fails with validate_failed");
+}
+`
+  }
+
+  return { code, tests }
+}
+
+
 function decl(varname: string, declared: Set<string>): string {
   if (declared.has(varname)) return ''
   declared.add(varname)

package/project/.sdk/src/cmp/cpp/fragment/Entity.fragment.cpp

@@ -34,6 +34,8 @@ public:
 
   // #UpdateOp
 
+  // #PatchOp
+
   // #RemoveOp
 };
 

package/project/.sdk/src/cmp/cpp/fragment/EntityPatchOp.fragment.cpp

@@ -0,0 +1,28 @@
+// EJECT-START
+
+  SdkEntityPtr patch(const Value& reqdata, const Value& ctrl) override {
+    CtxSpec cs;
+    cs.setOpname("patch");
+    cs.ctrlMap = ctrl.is_map() ? ctrl : vmap();
+    cs.match = this->match_;
+    cs.data = this->data_;
+    cs.reqdata = reqdata.is_map() ? reqdata : vmap();
+    CtxPtr ctx = this->utility->makeContext(cs, this->entctx);
+
+    runOp(ctx, [this, ctx]() {
+      if (ctx->result) {
+        if (!is_nullish(ctx->result->resdata)) {
+          Value d = Helpers::toMapAny(Struct::clone(ctx->result->resdata));
+          this->data_ = d.is_map() ? d : vmap();
+        }
+      }
+    });
+
+    // The operation resolves to THIS entity: runOp has just absorbed the
+    // result into it, and the caller reaches the record through data().
+    // See AGENTS.md "Entity operations return ENTITIES".
+
+    return this->self();
+  }
+
+// EJECT-END

package/project/.sdk/src/cmp/csharp/EntityTypes_csharp.ts

@@ -125,7 +125,7 @@ namespace ${model.const.Name}Sdk.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/csharp/Entity_csharp.ts

@@ -43,7 +43,7 @@ const Entity = cmp(function Entity(props: any) {
       // implementation (an override). Otherwise leave the base-class
       // virtual, which throws UnsupportedOp 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) ?

package/project/.sdk/src/cmp/csharp/Main_csharp.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
+  inactiveFeatureExcludes,
   pluginExcludes,
   TEST_CONTROL_EXCLUDE
 } from '@voxgig/sdkgen'
@@ -44,7 +45,8 @@ const Main = cmp(async function Main(props: any) {
 
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//, TEST_CONTROL_EXCLUDE, ...pluginExcludes(model)],
+    exclude: [/src\//, TEST_CONTROL_EXCLUDE,
+      ...inactiveFeatureExcludes(props.ctx$, target), ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }

package/project/.sdk/src/cmp/csharp/Package_csharp.ts

@@ -8,6 +8,7 @@ import {
   pkgDescription,
   repoInfo,
   packageVersion,
+  authorInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -21,6 +22,8 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
+import { xmlText } from './utility_csharp'
+
 
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
@@ -63,7 +66,7 @@ const Package = cmp(async function Package(props: any) {
     <!-- NuGet package metadata (publication pending; see Makefile). -->
     <Version>${packageVersion(model, target.name)}</Version>
     <PackageId>${Name}.Sdk</PackageId>
-    <Authors>Voxgig</Authors>
+    <Authors>${xmlText(authorInfo(model, target.name).name)}</Authors>
     <Description>${pkgDescription(model, target.name)}</Description>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <RepositoryUrl>${repoUrl}</RepositoryUrl>

package/project/.sdk/src/cmp/csharp/PrepareAuth_csharp.ts

@@ -110,7 +110,7 @@ function renderHeader(Name: string, cred: string, basic: boolean): string {
 
             if (noApikey)
             {
-                headers.Remove(HeaderAuth);
+                headers.Remove(name);
             }
             else
             {
@@ -124,7 +124,7 @@ function renderHeader(Name: string, cred: string, basic: boolean): string {
                 // The joined, encoded pair is a wire form neither credential's
                 // own registration covers.
                 ctx.Utility!.CleanAdd(ctx, b64);
-                headers[HeaderAuth] = basicPrefix == ""
+                headers[name] = basicPrefix == ""
                     ? b64
                     : basicPrefix + " " + b64;
             }
@@ -145,7 +145,7 @@ public static partial class SdkUtility
     private const string HeaderAuth = "${cred}";
     private const string OptionApikey = "apikey";${basicConst}
     private const string NotFound = "__NOTFOUND__";
-
+${authName('HeaderAuth', true)}
     internal static Spec PrepareAuthUtil(Context ctx)
     {
         var spec = ctx.Spec ?? throw ctx.MakeError("auth_no_spec",
@@ -161,6 +161,14 @@ public static partial class SdkUtility
             return spec;
         }
 
+        var name = PrepareAuthName(options);
+
+        // A credential left under the declared name would travel beside the renamed one.
+        if (name != HeaderAuth)
+        {
+            headers.Remove(HeaderAuth);
+        }
+
         var apikey = StructUtils.GetProp(options, OptionApikey, NotFound);
 ${basicBlock}
         var skip = apikey == null ||
@@ -168,7 +176,7 @@ ${basicBlock}
 
         if (skip)
         {
-            headers.Remove(HeaderAuth);
+            headers.Remove(name);
         }
         else
         {
@@ -179,7 +187,7 @@ ${basicBlock}
             }
             var apikeyVal = apikey as string ?? "";
             // Empty prefix (raw apiKey credential) must not add a leading space.
-            headers[HeaderAuth] = authPrefix == ""
+            headers[name] = authPrefix == ""
                 ? apikeyVal
                 : authPrefix + " " + apikeyVal;
         }
@@ -207,7 +215,7 @@ public static partial class SdkUtility
     private const string QueryAuth = "${cred}";
     private const string OptionApikey = "apikey";
     private const string NotFound = "__NOTFOUND__";
-
+${authName('QueryAuth', false)}
     internal static Spec PrepareAuthUtil(Context ctx)
     {
         var spec = ctx.Spec ?? throw ctx.MakeError("auth_no_spec",
@@ -223,6 +231,14 @@ public static partial class SdkUtility
             return spec;
         }
 
+        var name = PrepareAuthName(options);
+
+        // A credential left under the declared name would travel beside the renamed one.
+        if (name != QueryAuth)
+        {
+            query.Remove(QueryAuth);
+        }
+
         var apikey = StructUtils.GetProp(options, OptionApikey, NotFound);
 
         var skip = apikey == null ||
@@ -230,7 +246,7 @@ public static partial class SdkUtility
 
         if (skip)
         {
-            query.Remove(QueryAuth);
+            query.Remove(name);
         }
         else
         {
@@ -239,7 +255,7 @@ public static partial class SdkUtility
             // any API reads; the prefix is a header convention, so
             // options.auth.prefix is dropped here deliberately rather than
             // silently concatenated.
-            query[QueryAuth] = apikeyVal;
+            query[name] = apikeyVal;
         }
 
         return spec;
@@ -263,6 +279,26 @@ public static partial class SdkUtility
     private const string HeaderCookie = "cookie";
     private const string OptionApikey = "apikey";
     private const string NotFound = "__NOTFOUND__";
+${authName('CookieAuth', false)}
+    // Rewrites the cookie header with the named pair removed, then set to the
+    // value when it is not null; every other cookie is kept in order.
+    private static void PrepareAuthCookie(Dictionary<string, object?> headers, string name, string? value)
+    {
+        var existing = headers.TryGetValue(HeaderCookie, out var current) ? current as string : null;
+        var kept = CookieKeep(existing ?? "", new List<string> { name });
+        if (value != null)
+        {
+            kept.Add(name + "=" + value);
+        }
+        if (kept.Count == 0)
+        {
+            headers.Remove(HeaderCookie);
+        }
+        else
+        {
+            headers[HeaderCookie] = string.Join("; ", kept);
+        }
+    }
 
     internal static Spec PrepareAuthUtil(Context ctx)
     {
@@ -275,29 +311,27 @@ public static partial class SdkUtility
         // Public APIs that need no auth omit the options.auth block entirely.
         if (!options.TryGetValue("auth", out var auth) || auth == null)
         {
-            // Nothing of ours to remove: the credential rides INSIDE the
-            // shared cookie header, which this function only ever appends to.
-            // Returning here is what withholds it.
+            PrepareAuthCookie(headers, CookieAuth, null);
             return spec;
         }
 
+        var name = PrepareAuthName(options);
+
+        // A credential left under the declared name would travel beside the renamed one.
+        if (name != CookieAuth)
+        {
+            PrepareAuthCookie(headers, CookieAuth, null);
+        }
+
         var apikey = StructUtils.GetProp(options, OptionApikey, NotFound);
 
         var skip = apikey == null ||
             (apikey is string apikeyStr && (apikeyStr == NotFound || apikeyStr == ""));
 
-        if (!skip)
-        {
-            var apikeyVal = apikey as string ?? "";
-            // Append, never assign: a cookie header set by options.headers
-            // would otherwise be clobbered by the credential. No prefix - a
-            // cookie value is the credential itself.
-            var existing = StructUtils.GetProp(headers, HeaderCookie, "") as string ?? "";
-            var pair = CookieAuth + "=" + apikeyVal;
-            headers[HeaderCookie] = existing == ""
-                ? pair
-                : existing + "; " + pair;
-        }
+        // Spliced in, replacing an earlier pair of the same name, beside any
+        // cookie the caller set. No prefix - a cookie value is the credential
+        // itself.
+        PrepareAuthCookie(headers, name, skip ? null : apikey as string ?? "");
 
         return spec;
     }
@@ -306,6 +340,18 @@ public static partial class SdkUtility
 }
 
 
+// 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.
+    private static string PrepareAuthName(object? options) =>
+        StructUtils.GetPath(options, StructUtils.Jt("auth", "name")) is string name && name != ""
+            ? ${header ? 'name.ToLowerInvariant()' : 'name'} : ${declared};
+`
+}
+
+
 function csstr(s: string): string {
   return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
 }

package/project/.sdk/src/cmp/csharp/ReadmeEntity_csharp.ts

@@ -1,5 +1,5 @@
 
-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,
@@ -30,6 +30,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'List(null)',    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.' },
 }
 
@@ -55,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 || {})
     const idF = entityIdField(entity)
     // Sanitise the local variable name — a camelCased C# keyword gets a
@@ -111,7 +114,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.
@@ -133,7 +136,7 @@ var ${eVar} = client.${entity.Name}().Load(${loadArg});
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`csharp
@@ -143,7 +146,7 @@ var ${eVar}List = client.${entity.Name}().List(null);
 `)
     }
 
-    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 literal.

package/project/.sdk/src/cmp/csharp/ReadmeHowto_csharp.ts

@@ -39,7 +39,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'null'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `new Dictionary<string, object?> { ["${idF}"] = "test01" }` : 'null'
-  } 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)
@@ -51,9 +51,9 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // 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 raise on error.
+    ? `// Entity ops return the entity, and List one per record; they raise on error.
 var ${eVar} = client.${eName}().${opMethod}(${testArg});
-// ${eVar} holds the mock response record
+// Data() on an entity reads its mock response record
 Console.WriteLine(${eVar});`
     : `var result = client.Direct(new Dictionary<string, object?>
 {

package/project/.sdk/src/cmp/csharp/ReadmeInstall_csharp.ts

@@ -23,9 +23,9 @@ dotnet add reference ../${model.const.Name}SDK/${model.const.Name}SDK.csproj
 
   // Publish pending: not yet on NuGet. Install from the git release tag or
   // from a local source checkout.
-  const { releasesUrl } = repoInfo(model)
-  Content(`This package is not yet published to NuGet. 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 NuGet. Install it from the ${hostName}
+release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})) or
 from a source checkout — build the library and add a project reference:
 
 \`\`\`bash

package/project/.sdk/src/cmp/csharp/ReadmeIntro_csharp.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/csharp/ReadmeModel_csharp.ts

@@ -20,13 +20,14 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
-    load: '| `Load` | `(reqmatch, ctrl) -> object?` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `List` | `(reqmatch, ctrl) -> object?` | List entities matching the criteria (an aggregate list). Raises on error. |',
-    create: '| `Create` | `(reqdata, ctrl) -> object?` | Create a new entity. Raises on error. |',
-    update: '| `Update` | `(reqdata, ctrl) -> object?` | Update an existing entity. Raises on error. |',
-    remove: '| `Remove` | `(reqmatch, ctrl) -> object?` | Remove an entity. Raises on error. |',
+    load: '| `Load` | `(reqmatch, ctrl) -> object?` | Load a single entity by match criteria, and return it. Raises on error. |',
+    list: '| `List` | `(reqmatch, ctrl) -> object?` | List entities matching the criteria, one per record. Raises on error. |',
+    create: '| `Create` | `(reqdata, ctrl) -> object?` | Create a new entity, and return it. Raises on error. |',
+    update: '| `Update` | `(reqdata, ctrl) -> object?` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `Patch` | `(reqdata, ctrl) -> object?` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `Remove` | `(reqmatch, ctrl) -> object?` | Remove an entity, and return it marked as deleted. 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)
@@ -91,9 +92,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (a \`Dictionary\` for
-single-entity ops, an aggregate list for \`List\`) as \`object?\` and raise on
-error. Wrap calls in \`try\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`List\` a list of entities, one per
+record, as \`object?\`; an entity is an \`IEntity\`, whose \`Data()\` reads its
+record. They raise on error, so wrap calls in \`try\`/\`catch\` to handle
+failures.
 
 The \`Direct()\` escape hatch never raises — it returns a result
 \`Dictionary<string, object?>\` you branch on via \`result["ok"]\`: