@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/src/cmp/zig/PrepareAuth_zig.ts

@@ -97,7 +97,7 @@ const CRED_NAME = ${zigstr(credLiteral(spec.where, spec.name))};
 const OPTION_APIKEY = "apikey";
 ` + (withBasic ? `const OPTION_SECRET = "secret";
 ` : '') + `const NOT_FOUND = "__NOTFOUND__";
-` + (withBasic ? basicHelpers() : '') + `
+` + authName(true) + (withBasic ? basicHelpers() : '') + `
 pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     const spec = ctx.spec orelse return ctx.fail("auth_no_spec", "Expected context spec property to be defined.");
 
@@ -111,6 +111,13 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
         return spec;
     }
 
+    const name = auth_name(options);
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (!std.mem.eql(u8, name, CRED_NAME)) {
+        h.del_prop(headers, h.vstr(CRED_NAME));
+    }
+
     const apikey = vs.getprop(h.A(), options, h.vstr(OPTION_APIKEY), h.vstr(NOT_FOUND)) catch h.vstr(NOT_FOUND);
 
     const skip = switch (apikey) {
@@ -120,7 +127,7 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     };
 ` + (withBasic ? basicBlock() : '') + `
     if (skip) {
-        h.del_prop(headers, h.vstr(CRED_NAME));
+        h.del_prop(headers, h.vstr(name));
     } else {
         const auth_prefix: []const u8 = switch (h.getpath(&.{ "auth", "prefix" }, options)) {
             .string => |s| s,
@@ -133,9 +140,9 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
         // 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 (auth_prefix.len == 0) {
-            h.setp(headers, CRED_NAME, h.vstr(apikey_val));
+            h.setp(headers, name, h.vstr(apikey_val));
         } else {
-            h.setp(headers, CRED_NAME, h.vstr(fmt("{s} {s}", .{ auth_prefix, apikey_val })));
+            h.setp(headers, name, h.vstr(fmt("{s} {s}", .{ auth_prefix, apikey_val })));
         }
     }
 
@@ -151,7 +158,7 @@ function renderQuery(spec: AuthSpec): string {
 const CRED_NAME = ${zigstr(credLiteral(spec.where, spec.name))};
 const OPTION_APIKEY = "apikey";
 const NOT_FOUND = "__NOTFOUND__";
-
+` + authName(false) + `
 pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     const spec = ctx.spec orelse return ctx.fail("auth_no_spec", "Expected context spec property to be defined.");
 
@@ -165,6 +172,13 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
         return spec;
     }
 
+    const name = auth_name(options);
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (!std.mem.eql(u8, name, CRED_NAME)) {
+        h.del_prop(query, h.vstr(CRED_NAME));
+    }
+
     const apikey = vs.getprop(h.A(), options, h.vstr(OPTION_APIKEY), h.vstr(NOT_FOUND)) catch h.vstr(NOT_FOUND);
 
     const skip = switch (apikey) {
@@ -174,7 +188,7 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     };
 
     if (skip) {
-        h.del_prop(query, h.vstr(CRED_NAME));
+        h.del_prop(query, h.vstr(name));
     } else {
         const apikey_val: []const u8 = switch (apikey) {
             .string => |s| s,
@@ -185,7 +199,7 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
         // dropped here deliberately rather than silently concatenated. Nor is
         // there an HTTP Basic branch - \`Authorization: Basic base64(u:p)\`
         // cannot be a query parameter.
-        h.setp(query, CRED_NAME, h.vstr(apikey_val));
+        h.setp(query, name, h.vstr(apikey_val));
     }
 
     return spec;
@@ -205,36 +219,26 @@ const COOKIE_HEADER = "cookie";
 const CRED_NAME = ${zigstr(credLiteral(spec.where, spec.name))};
 const OPTION_APIKEY = "apikey";
 const NOT_FOUND = "__NOTFOUND__";
-
-// The cookie header minus our own pair, every other cookie left alone.
-fn cookies_without_cred(headers: Value) []const u8 {
+` + authName(false) + `
+// The cookie header minus the named pair, every other cookie left alone.
+fn cookies_without_cred(headers: Value, name: []const u8) []const u8 {
     const existing: []const u8 = switch (h.getp(headers, COOKIE_HEADER)) {
         .string => |s| s,
         else => "",
     };
     if (existing.len == 0) return "";
 
-    var kept: []const u8 = "";
-    var it = std.mem.splitScalar(u8, existing, ';');
-    while (it.next()) |part| {
-        const piece = std.mem.trim(u8, part, " \\t");
-        if (piece.len == 0) continue;
-        if (std.mem.eql(u8, piece, CRED_NAME)) continue;
-        if (std.mem.startsWith(u8, piece, CRED_NAME ++ "=")) continue;
-        kept = if (kept.len == 0) piece else fmt("{s}; {s}", .{ kept, piece });
-    }
-
-    return kept;
+    return std.mem.join(h.A(), "; ", h.cookie_keep(existing, &[_][]const u8{name})) catch "";
 }
 
-// Set (a value) or remove (null) our pair, leaving every other cookie in place.
-fn apply_cookie(headers: Value, value: ?[]const u8) void {
-    const rest = cookies_without_cred(headers);
+// Set (a value) or remove (null) the named pair, leaving every other cookie in place.
+fn apply_cookie(headers: Value, name: []const u8, value: ?[]const u8) void {
+    const rest = cookies_without_cred(headers, name);
 
     if (value) |v| {
         // NO PREFIX IN A COOKIE either - a cookie carries a bare \`name=value\`
         // pair, not a header's scheme-prefixed credential.
-        const pair = fmt("{s}={s}", .{ CRED_NAME, v });
+        const pair = fmt("{s}={s}", .{ name, v });
         h.setp(headers, COOKIE_HEADER, h.vstr(if (rest.len == 0) pair else fmt("{s}; {s}", .{ rest, pair })));
         return;
     }
@@ -255,10 +259,17 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     // Public APIs that need no auth omit the options.auth block entirely.
     const auth = h.getp(options, "auth");
     if (h.is_noval(auth)) {
-        apply_cookie(headers, null);
+        apply_cookie(headers, CRED_NAME, null);
         return spec;
     }
 
+    const name = auth_name(options);
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if (!std.mem.eql(u8, name, CRED_NAME)) {
+        apply_cookie(headers, CRED_NAME, null);
+    }
+
     const apikey = vs.getprop(h.A(), options, h.vstr(OPTION_APIKEY), h.vstr(NOT_FOUND)) catch h.vstr(NOT_FOUND);
 
     const skip = switch (apikey) {
@@ -268,13 +279,13 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
     };
 
     if (skip) {
-        apply_cookie(headers, null);
+        apply_cookie(headers, name, null);
     } else {
         const apikey_val: []const u8 = switch (apikey) {
             .string => |s| s,
             else => "",
         };
-        apply_cookie(headers, apikey_val);
+        apply_cookie(headers, name, apikey_val);
     }
 
     return spec;
@@ -283,6 +294,21 @@ pub fn prepare_auth_util(ctx: *Context) E!*Spec {
 }
 
 
+// The client's `auth.name` option, when set, replaces the declared name; a
+// header name travels lower-cased.
+function authName(header: boolean): string {
+  return `
+// The client's auth.name option, when set, replaces the name the API declares.
+fn auth_name(options: Value) []const u8 {
+    return switch (h.getpath(&.{ "auth", "name" }, options)) {
+        .string => |s| if (s.len == 0) CRED_NAME else ${header ? 'std.ascii.allocLowerString(h.A(), s) catch CRED_NAME' : 's'},
+        else => CRED_NAME,
+    };
+}
+`
+}
+
+
 function imports(need: { vs: boolean, fmt: boolean }): string {
   return `
 const std = @import("std");
@@ -345,7 +371,7 @@ function basicBlock(): string {
         };
 
         if (skip) {
-            h.del_prop(headers, h.vstr(CRED_NAME));
+            h.del_prop(headers, h.vstr(name));
         } else {
             const basic_prefix: []const u8 = switch (h.getpath(&.{ "auth", "prefix" }, options)) {
                 .string => |s| s,
@@ -364,9 +390,9 @@ function basicBlock(): string {
             // registration covers.
             ctx.util().clean_add(ctx, b64);
             if (basic_prefix.len == 0) {
-                h.setp(headers, CRED_NAME, h.vstr(b64));
+                h.setp(headers, name, h.vstr(b64));
             } else {
-                h.setp(headers, CRED_NAME, h.vstr(fmt("{s} {s}", .{ basic_prefix, b64 })));
+                h.setp(headers, name, h.vstr(fmt("{s} {s}", .{ basic_prefix, b64 })));
             }
         }
 

package/project/.sdk/src/cmp/zig/ReadmeEntity_zig.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,
@@ -41,6 +41,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(reqmatch, ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
   create: { method: 'create(reqdata, ctrl)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(reqdata, ctrl)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(reqdata, ctrl)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(reqmatch, ctrl)', desc: 'Remove the matching entity.' },
 }
 
@@ -66,6 +67,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
     const eVar = zigVarName(entity.name)
@@ -101,8 +104,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       })
 
       Content(`
-Each operation returns an \`OpResult\` — \`switch\` on it: \`.ok => |data|\`
-carries the result \`Value\`, \`.err => |e|\` carries the branded error.
+Each operation returns a result union — \`switch\` on it: \`.ok\` carries the
+entity (for \`list\`, a slice of entities, one per record), whose record
+\`asEntity().data(null)\` reads, and \`.err => |e|\` the branded error.
 
 `)
     }
@@ -124,7 +128,7 @@ carries the result \`Value\`, \`.err => |e|\` carries the branded error.
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -138,7 +142,7 @@ carries the result \`Value\`, \`.err => |e|\` carries the branded error.
 
 \`\`\`zig
 switch (client.${method}(h.vnull()).load(${loadArg}, h.vnull())) {
-    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}),
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar}.asEntity().data(null))}),
     .err => |e| std.debug.print("load failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
@@ -146,12 +150,16 @@ switch (client.${method}(h.vnull()).load(${loadArg}, h.vnull())) {
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`zig
 switch (client.${method}(h.vnull()).list(h.vnull(), h.vnull())) {
-    .ok => |${eVar}s| std.debug.print("{s}\\n", .{h.stringify(${eVar}s)}),
+    .ok => |${eVar}s| {
+        for (${eVar}s) |${eVar}| {
+            std.debug.print("{s}\\n", .{h.stringify(${eVar}.asEntity().data(null))});
+        }
+    },
     .err => |e| std.debug.print("list failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
@@ -159,7 +167,7 @@ switch (client.${method}(h.vnull()).list(h.vnull(), h.vnull())) {
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -172,7 +180,7 @@ switch (client.${method}(h.vnull()).create(h.jo(&.{
 `)
       })
       Content(`}), h.vnull())) {
-    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}),
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar}.asEntity().data(null))}),
     .err => |e| std.debug.print("create failed: {s}\\n", .{e.msg}),
 }
 \`\`\`

package/project/.sdk/src/cmp/zig/ReadmeHowto_zig.ts

@@ -36,7 +36,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'h.vnull()'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `h.jo(&.{.{ "${idF}", h.vstr("test01") }})` : 'h.vnull()'
-  } 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)
@@ -47,10 +47,20 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   }
 
   // The op-driven test-mode line. A direct()-only SDK shows a direct() call.
-  const testModeExample = primaryOp
-    ? `// Entity ops return an OpResult — .ok carries the record, .err the error.
+  const testModeExample = 'list' === primaryOp
+    ? `// list's .ok is one entity per mock record, .err the error.
+switch (client.${method}(h.vnull()).list(${testArg}, h.vnull())) {
+    .ok => |${eVar}s| {
+        for (${eVar}s) |${eVar}| {
+            std.debug.print("{s}\\n", .{h.stringify(${eVar}.asEntity().data(null))});
+        }
+    },
+    .err => |e| std.debug.print("list failed: {s}\\n", .{e.msg}),
+}`
+    : primaryOp
+    ? `// Entity ops return a result union — .ok carries the entity, .err the error.
 switch (client.${method}(h.vnull()).${primaryOp}(${testArg}, h.vnull())) {
-    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}), // the mock record
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar}.asEntity().data(null))}), // the mock record
     .err => |e| std.debug.print("${primaryOp} failed: {s}\\n", .{e.msg}),
 }`
     : `const result = client.direct(h.jo(&.{

package/project/.sdk/src/cmp/zig/ReadmeInstall_zig.ts

@@ -24,9 +24,9 @@ cd ${target.name} && zig build
   // Zig has no central package registry — the release IS the git tag. Depend
   // on it via the Zig package manager (a git-tagged url in build.zig.zon) or
   // build from a local source checkout.
-  const { releasesUrl } = repoInfo(model)
+  const { tagsUrl } = repoInfo(model)
   Content(`Zig has no central package registry, so this package is distributed as a
-git tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})). Add it to
+git tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})). Add it to
 your \`build.zig.zon\` dependencies, or build from a source checkout:
 
 \`\`\`bash

package/project/.sdk/src/cmp/zig/ReadmeIntro_zig.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import { zigVarName } from './utility_zig'
 
 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 ${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/zig/ReadmeModel_zig.ts

@@ -21,13 +21,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: Value, ctrl: Value) OpResult` | Load a single entity by match criteria. |',
-    list: '| `list` | `(reqmatch: Value, ctrl: Value) OpResult` | List entities matching the criteria (`.ok` is a `Value` array). |',
-    create: '| `create` | `(reqdata: Value, ctrl: Value) OpResult` | Create a new entity. |',
-    update: '| `update` | `(reqdata: Value, ctrl: Value) OpResult` | Update an existing entity. |',
-    remove: '| `remove` | `(reqmatch: Value, ctrl: Value) OpResult` | Remove an entity. |',
+    load: '| `load` | `(reqmatch: Value, ctrl: Value) EntResult` | Load a single entity by match criteria. |',
+    list: '| `list` | `(reqmatch: Value, ctrl: Value) EntListResult` | List entities matching the criteria (`.ok` is a slice of entities, one per record). |',
+    create: '| `create` | `(reqdata: Value, ctrl: Value) EntResult` | Create a new entity. |',
+    update: '| `update` | `(reqdata: Value, ctrl: Value) EntResult` | Update an existing entity. |',
+    patch: '| `patch` | `(reqdata: Value, ctrl: Value) EntResult` | Change part of an existing entity. |',
+    remove: '| `remove` | `(reqmatch: Value, ctrl: Value) EntResult` | Remove an entity, which is returned marked as deleted. |',
   }
-  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)
@@ -87,16 +88,17 @@ All entities share the same interface.
 | Method | Signature | Description |
 | --- | --- | --- |
 ${opRows}
-| \`stream\` | \`(action: []const u8, args: Value, callopts: Value) []Value\` | Run an op through the pipeline and materialise its result items. |
+| \`stream\` | \`(action: []const u8, args: Value, callopts: Value) StreamResult\` | Run an op through the pipeline: \`.ok\` with its result items, or \`.err\` with the error that failed it. |
 | \`data\` | \`(args: ?Value) Value\` | Get entity data (pass a map to set). |
 | \`matchv\` | \`(args: ?Value) Value\` | Get entity match criteria (pass a map to set). |
 | \`get_name\` | \`() []const u8\` | Return the entity name. |
 
 ### Result shape
 
-Entity operations return an \`OpResult\` union — \`switch\` on it: \`.ok\`
-carries the bare result data (a \`Value\` object for single-entity ops, a
-\`Value\` array for \`list\`), \`.err\` carries the branded error pointer.
+Entity operations return a result union — \`switch\` on it: \`.ok\` carries
+the entity (\`EntResult\`), or for \`list\` a slice of entities, one per record
+(\`EntListResult\`), and \`asEntity().data(null)\` reads an entity's record;
+\`.err\` carries the branded error pointer.
 
 The \`direct()\` escape hatch returns a result \`Value\` map directly (no
 error union) — even on a non-2xx response — that you branch on via

package/project/.sdk/src/cmp/zig/ReadmeQuick_zig.ts

@@ -66,12 +66,16 @@ const client = ${ctor};
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` returns an \`OpResult\` whose \`.ok\` is a \`Value\` array —
-\`switch\` on it.
+\`list()\`'s \`.ok\` is a slice of entities, one per record — \`switch\` on
+it. \`asEntity().data(null)\` reads an entity's record.
 
 \`\`\`zig
 switch (client.${method}(h.vnull()).list(h.vnull(), h.vnull())) {
-    .ok => |${eVar}s| std.debug.print("{s}\\n", .{h.stringify(${eVar}s)}),
+    .ok => |${eVar}s| {
+        for (${eVar}s) |${eVar}| {
+            std.debug.print("{s}\\n", .{h.stringify(${eVar}.asEntity().data(null))});
+        }
+    },
     .err => |e| std.debug.print("list failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
@@ -100,11 +104,12 @@ switch (client.${method}(h.vnull()).list(h.vnull(), h.vnull())) {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\`'s \`.ok\` carries the bare record.
+\`load()\`'s \`.ok\` carries the entity; \`asEntity().data(null)\` reads its
+record.
 
 \`\`\`zig
 switch (client.${neMethod}(h.vnull()).load(h.jo(&.{${neMatch.join(', ')}}), h.vnull())) {
-    .ok => |${neVar}| std.debug.print("{s}\\n", .{h.stringify(${neVar})}),
+    .ok => |${neVar}| std.debug.print("{s}\\n", .{h.stringify(${neVar}.asEntity().data(null))}),
     .err => |e| std.debug.print("load failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
@@ -124,11 +129,12 @@ switch (client.${neMethod}(h.vnull()).load(h.jo(&.{${neMatch.join(', ')}}), h.vn
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\`'s \`.ok\` carries the bare record.
+\`load()\`'s \`.ok\` carries the entity; \`asEntity().data(null)\` reads its
+record.
 
 \`\`\`zig
 switch (client.${method}(h.vnull()).load(${loadArg}, h.vnull())) {
-    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}),
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar}.asEntity().data(null))}),
     .err => |e| std.debug.print("load failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
@@ -156,15 +162,16 @@ switch (client.${method}(h.vnull()).load(${loadArg}, h.vnull())) {
     }
     const idValueFor = (opname: string): string => zigLit(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
 
 \`\`\`zig
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — .ok carries the created record
+        Content(`// Create — .ok carries the created entity
 switch (client.${method}(h.vnull()).create(h.jo(&.{${examplePairs('create').join(', ')}}), h.vnull())) {
-    .ok => |created| std.debug.print("{s}\\n", .{h.stringify(created)}),
+    .ok => |created| std.debug.print("{s}\\n", .{h.stringify(created.asEntity().data(null))}),
     .err => |e| std.debug.print("create failed: {s}\\n", .{e.msg}),
 }
 
@@ -174,10 +181,20 @@ switch (client.${method}(h.vnull()).create(h.jo(&.{${examplePairs('create').join
         const updatePairs = (idF ? [`.{ "${idF}", ${idValueFor('update')} }`] : []).concat(examplePairs('update'))
         Content(`// Update
 switch (client.${method}(h.vnull()).update(h.jo(&.{${updatePairs.join(', ')}}), h.vnull())) {
-    .ok => |updated| std.debug.print("{s}\\n", .{h.stringify(updated)}),
+    .ok => |updated| std.debug.print("{s}\\n", .{h.stringify(updated.asEntity().data(null))}),
     .err => |e| std.debug.print("update failed: {s}\\n", .{e.msg}),
 }
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`.{ "${idF}", ${idValueFor('patch')} }`] : []).concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+switch (client.${method}(h.vnull()).patch(h.jo(&.{${patchPairs.join(', ')}}), h.vnull())) {
+    .ok => |patched| std.debug.print("{s}\\n", .{h.stringify(patched)}),
+    .err => |e| std.debug.print("patch failed: {s}\\n", .{e.msg}),
+}
+
 `)
       }
       if (opnames.includes('remove')) {
@@ -190,7 +207,7 @@ switch (client.${method}(h.vnull()).update(h.jo(&.{${updatePairs.join(', ')}}),
             : `.{ "${it.name}", ${zigLit(it.type, 'example_' + it.name)} }`)
         Content(`// Remove
 switch (client.${method}(h.vnull()).remove(${removePairs.length ? `h.jo(&.{${removePairs.join(', ')}})` : 'h.vnull()'}, h.vnull())) {
-    .ok => |_| std.debug.print("removed\\n", .{}),
+    .ok => std.debug.print("removed\\n", .{}),
     .err => |e| std.debug.print("remove failed: {s}\\n", .{e.msg}),
 }
 `)

package/project/.sdk/src/cmp/zig/ReadmeRef_zig.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 {
@@ -45,24 +45,28 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
 
   const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
     load: {
-      sig: 'load(reqmatch: Value, ctrl: Value) OpResult',
-      desc: 'Load a single entity matching the given criteria. `.ok` carries the entity data, `.err` the branded error.',
+      sig: 'load(reqmatch: Value, ctrl: Value) EntResult',
+      desc: 'Load a single entity matching the given criteria. `.ok` carries the entity, whose record `asEntity().data(null)` reads, and `.err` the branded error.',
     },
     list: {
-      sig: 'list(reqmatch: Value, ctrl: Value) OpResult',
-      desc: 'List entities matching the given criteria. The match is optional — pass `h.vnull()` to list all records. `.ok` is a `Value` array.',
+      sig: 'list(reqmatch: Value, ctrl: Value) EntListResult',
+      desc: 'List entities matching the given criteria. The match is optional — pass `h.vnull()` to list all records. `.ok` is a slice of entities, one per record.',
     },
     create: {
-      sig: 'create(reqdata: Value, ctrl: Value) OpResult',
-      desc: 'Create a new entity with the given data. `.ok` carries the created entity data.',
+      sig: 'create(reqdata: Value, ctrl: Value) EntResult',
+      desc: 'Create a new entity with the given data. `.ok` carries the created entity.',
     },
     update: {
-      sig: 'update(reqdata: Value, ctrl: Value) OpResult',
-      desc: 'Update an existing entity. The data must include the entity id. `.ok` carries the updated entity data.',
+      sig: 'update(reqdata: Value, ctrl: Value) EntResult',
+      desc: 'Update an existing entity. The data must include the entity id. `.ok` carries the updated entity.',
+    },
+    patch: {
+      sig: 'patch(reqdata: Value, ctrl: Value) OpResult',
+      desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity id. `.ok` carries the patched entity data.',
     },
     remove: {
-      sig: 'remove(reqmatch: Value, ctrl: Value) OpResult',
-      desc: 'Remove the entity matching the given criteria. `.err` on failure.',
+      sig: 'remove(reqmatch: Value, ctrl: Value) EntResult',
+      desc: 'Remove the entity matching the given criteria. `.ok` carries the entity, marked as deleted, and `.err` the branded error.',
     },
   }
 
@@ -220,7 +224,7 @@ const ${eVar} = client.${method}(h.vnull());
         // 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
 
@@ -261,6 +265,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)
@@ -273,7 +281,7 @@ ${info.desc}
               : 'h.vnull()'
             Content(`\`\`\`zig
 switch (client.${method}(h.vnull()).${opname}(${arg}, h.vnull())) {
-    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result)}),
+    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result.asEntity().data(null))}),
     .err => |e| std.debug.print("${opname} failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
@@ -283,7 +291,11 @@ switch (client.${method}(h.vnull()).${opname}(${arg}, h.vnull())) {
           else if ('list' === opname) {
             Content(`\`\`\`zig
 switch (client.${method}(h.vnull()).list(h.vnull(), h.vnull())) {
-    .ok => |results| std.debug.print("{s}\\n", .{h.stringify(results)}),
+    .ok => |results| {
+        for (results) |result| {
+            std.debug.print("{s}\\n", .{h.stringify(result.asEntity().data(null))});
+        }
+    },
     .err => |e| std.debug.print("list failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
@@ -301,15 +313,15 @@ switch (client.${method}(h.vnull()).create(h.jo(&.{
 `)
             })
             Content(`}), h.vnull())) {
-    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result)}),
+    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result.asEntity().data(null))}),
     .err => |e| std.debug.print("create failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
 
 `)
           }
-          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))
@@ -317,16 +329,23 @@ switch (client.${method}(h.vnull()).create(h.jo(&.{
               `    .{ "${it.name}", ${zigLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)} },\n`).join('')
             Content(`\`\`\`zig
-switch (client.${method}(h.vnull()).update(h.jo(&.{
-${updateLines}    // Fields to update
+switch (client.${method}(h.vnull()).${opname}(h.jo(&.{
+${updateLines}    // ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 }), h.vnull())) {
-    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result)}),
-    .err => |e| std.debug.print("update failed: {s}\\n", .{e.msg}),
+    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result.asEntity().data(null))}),
+    .err => |e| std.debug.print("${opname} failed: {s}\\n", .{e.msg}),
 }
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a string value holding the bytes',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 
@@ -342,9 +361,13 @@ Get the entity data. Pass a map to set it.
 
 Get the entity match criteria. Pass a map to set it.
 
-#### \`stream(action: []const u8, args: Value, callopts: Value) []Value\`
+#### \`stream(action: []const u8, args: Value, callopts: Value) StreamResult\`
 
 Run an operation through the pipeline and materialise its result items.
+\`StreamResult\` is \`.ok\` with the items, or \`.err\` with the error that
+failed the operation, as an operation call reports it. Under \`throw: false\`
+in \`callopts.ctrl\`, a failed stream is \`.ok\` with whatever data the
+failure left.
 
 #### \`get_name() []const u8\`