@voxgig/sdkgen 2.0.2 → 3.1.0

package/project/.sdk/src/cmp/kotlin/TestEntity_kotlin.ts

@@ -17,7 +17,7 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -56,8 +56,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
     return
   }
 
-  const PROJUPPER = nom(model.const, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
-  const ENTUPPER = entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJUPPER = envName(model)
+  const ENTUPPER = envToken(entity.name)
   const entidEnvVar = `${PROJUPPER}_TEST_${ENTUPPER}_ENTID`
 
   const SDK = model.const.Name + 'SDK'
@@ -317,7 +317,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
   Content(`
     val ${datavar}Result = ${entvar}.create(${datavar}, null)
-    ${datavar} = Helpers.toMapAny(${datavar}Result) ?: linkedMapOf()
+    ${datavar} = Helpers.toMapAny(if (${datavar}Result is SdkEntity) ${datavar}Result.data() else ${datavar}Result) ?: linkedMapOf()
     assertNotNull(${datavar}, "expected create result to be a map")
 `)
   if (null != ctx.entity.id) {
@@ -451,7 +451,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
   Content(`
     val ${resdatavar}Result = ${entvar}.update(${datavar}Up, null)
-    val ${resdatavar} = Helpers.toMapAny(${resdatavar}Result) ?: linkedMapOf()
+    val ${resdatavar} = Helpers.toMapAny(if (${resdatavar}Result is SdkEntity) ${resdatavar}Result.data() else ${resdatavar}Result) ?: linkedMapOf()
     assertNotNull(${resdatavar}, "expected update result to be a map")
 `)
   if (hasEntIdU) {
@@ -516,7 +516,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
   if (hasEntId) {
     Content(`    ${matchvar}["id"] = ${srcdatavar}["id"]
     val ${datavar}Loaded = ${entvar}.load(${matchvar}, null)
-    val ${datavar}LoadResult = Helpers.toMapAny(${datavar}Loaded) ?: linkedMapOf()
+    val ${datavar}LoadResult = Helpers.toMapAny(if (${datavar}Loaded is SdkEntity) ${datavar}Loaded.data() else ${datavar}Loaded) ?: linkedMapOf()
     assertNotNull(${datavar}LoadResult, "expected load result to be a map")
     assertEquals(${srcdatavar}["id"], ${datavar}LoadResult["id"],
         "expected load result id to match")

package/project/.sdk/src/cmp/kotlin/fragment/EntityBase.fragment.kt

@@ -71,6 +71,18 @@ abstract class EntityBase(nm: String, clientIn: SdkClient, entoptsIn: MutableMap
   // runOp drives one operation through the pipeline: for each stage the
   // feature hook fires, then the stage runs; a failing stage routes through
   // makeError (which throws, or returns fallback data when ctrl.throw false).
+  // Every operation resolves to the entity; `remove` additionally marks
+  // it. The instance KEEPS the data it held — a caller can still read
+  // what was deleted — but it is no longer a live record. See AGENTS.md.
+  private var deletedFlag: Boolean = false
+
+  fun markDeleted() {
+    this.deletedFlag = true
+  }
+
+  fun deleted(): Boolean = this.deletedFlag
+
+
   protected fun runOp(ctx: Context, postDone: () -> Unit): Any? {
     val utility = this.utility
 
@@ -104,7 +116,26 @@ abstract class EntityBase(nm: String, clientIn: SdkClient, entoptsIn: MutableMap
 
       postDone()
 
-      return utility.done(ctx)
+      val out = utility.done(ctx)
+
+      // An operation resolves to the ENTITY, not the raw data. Entities are
+      // stateful: postDone has just absorbed resdata/resmatch into this
+      // instance, and the caller reaches the record through data(). Two
+      // structural exceptions: `list` resolves to the ARRAY of entity
+      // instances makeResult built, and a failed op with throwing disabled
+      // hands back the error payload unchanged. `remove` additionally marks
+      // the entity deleted; it KEEPS its data, so a caller can still read
+      // what was removed. See AGENTS.md "Entity operations return ENTITIES".
+      val opname = ctx.op?.name
+
+      if (ctx.result != null && ctx.result!!.ok && "list" != opname) {
+        if ("remove" == opname) {
+          this.markDeleted()
+        }
+        return this
+      }
+
+      return out
     } catch (err: RuntimeException) {
       // An error already finalised by makeError (e.g. via done) must not be
       // wrapped a second time.

package/project/.sdk/src/cmp/lean/Package_lean.ts

@@ -2,6 +2,7 @@ import {
   Content,
   File,
   cmp,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 import type {
@@ -22,6 +23,7 @@ const LIBS = [
 
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
+  const target = props.target
   const model: Model = ctx$.model
 
   const libBlocks = LIBS.map((n) =>
@@ -30,7 +32,7 @@ const Package = cmp(async function Package(props: any) {
   File({ name: 'lakefile.toml' }, () => {
     Content(`# ${model.const.Name} SDK for Lean 4 (generated by @voxgig/sdkgen).
 name = "${pkgName(model)}"
-version = "0.0.1"
+version = "${packageVersion(model, target.name)}"
 defaultTargets = ["SdkClient"]
 
 ${libBlocks}

package/project/.sdk/src/cmp/lua/MainEntity_lua.ts

@@ -1,11 +1,16 @@
 
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, entityCacheField } from '@voxgig/sdkgen'
 
 
 const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
   const { model } = props.ctx$
+  // The cache slot must not alias one of the SDK's own fields: an entity
+  // named `utility` made client:Utility() hand back self._utility, the SDK's
+  // internal utility object, whose :load() is nil.
+  const field = entityCacheField(entity.name)
+
 
   Content(`
 -- Idiomatic facade: client:${entity.Name}():list() / client:${entity.Name}():load({ id = ... })
@@ -13,10 +18,10 @@ const MainEntity = cmp(async function MainEntity(props: any) {
 function ${model.const.Name}SDK:${entity.Name}(data)
   local EntityMod = require("entity.${entity.name}_entity")
   if data == nil then
-    if self._${entity.name} == nil then
-      self._${entity.name} = EntityMod.new(self, nil)
+    if self._${field} == nil then
+      self._${field} = EntityMod.new(self, nil)
     end
-    return self._${entity.name}
+    return self._${field}
   end
   return EntityMod.new(self, data)
 end

package/project/.sdk/src/cmp/lua/Package_lua.ts

@@ -6,7 +6,8 @@ import {
   collectDeps,
   pkgDescription,
   keywords,
-  repoInfo,
+  repoInfo, packageName,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -26,13 +27,13 @@ const Package = cmp(async function Package(props: any) {
   // (`${model.name}_sdk`) used by `require` is unchanged.
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
-  const rockName = `${ns}-${pkgBase}`
+  const rockName = packageName(model, 'lua')
   const { repoUrl, issuesUrl } = repoInfo(model)
   const labels = keywords(model).map((k) => `"${k}"`).join(', ')
 
   // Single source for the version so the rockspec version and the source.tag
   // (which `make publish` pushes as lua/v<rockVersion>) can never drift apart.
-  const rockVersion = '0.0.1'
+  const rockVersion = packageVersion(model, target.name)
 
   File({ name: model.name + '.rockspec' }, () => {
     Content(`package = "${rockName}"

package/project/.sdk/src/cmp/lua/ReadmeModel_lua.ts

@@ -40,9 +40,16 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   if (opUnion.has('list')) resultRows.push('| `list` | an array (`table`) of entity records |')
   const resultShapeRows = resultRows.join('\n')
 
-  const exEnt: any = entityList[0] || {}
+  // The Result-shape illustration calls `load`, so the example entity must
+  // actually HAVE load — entityList[0] need not. api-tools' first entity is
+  // Cryptography (create-only), so the generated README demonstrated
+  // `client:Cryptography():load()` and the readme_examples test died with
+  // "attempt to call a nil value (method 'load')".
+  const exEnt: any =
+    entityList.find((e: any) => (e.op || {}).load) || entityList[0] || {}
   const eName = exEnt.Name || 'Entity'
   const eLower = String(exEnt.name || 'entity').toLowerCase()
+  const hasLoad = null != (exEnt.op || {}).load
   // Model-driven id key: null when the example entity has no id-like field, so
   // the Result-shape load illustration takes no match argument.
   const idF = entityIdField(exEnt)
@@ -119,9 +126,10 @@ ${resultShapeRows}
 
 Check \`err\` first (it is non-\`nil\` on failure), then use \`value\`:
 
-    local ${eLower}, err = client:${eName}():load(${idF ? `{ ${idF} = "example_id" }` : ''})
+    local ${eLower}, err = client:${eName}():${hasLoad ? 'load' : 'list'}(${
+      hasLoad && idF ? `{ ${idF} = "example_id" }` : ''})
     if err then error(err) end
-    -- ${eLower} is the loaded record
+    -- ${eLower} is the ${hasLoad ? 'loaded record' : 'record list'}
 
 Only \`direct()\` returns a response envelope — a \`table\` with \`ok\`,
 \`status\`, \`headers\`, and \`data\` keys.

package/project/.sdk/src/cmp/lua/ReadmeQuick_lua.ts

@@ -190,7 +190,7 @@ print(${eVar})
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `created["${dataIdF}"]`
+      ? `created:data_get()["${dataIdF}"]`
       : luaLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {

package/project/.sdk/src/cmp/lua/TestDirect_lua.ts

@@ -11,7 +11,7 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -60,7 +60,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const target = props.target
   const entity: ModelEntity = props.entity
 
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJECTNAME = envName(model)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -125,7 +125,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     ? loadParams.map((p: any) => `      params["${p.name}"] = ${JSON.stringify(p.example)}`).join('\n')
     : ''
 
-  const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
+  const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
   File({ name: entity.name + '_direct_test.' + target.ext }, () => {
 

package/project/.sdk/src/cmp/lua/TestEntity_lua.ts

@@ -24,7 +24,7 @@ import {
   buildIdNames,
   getMatchEntries,
   isAuthActive,
-  entityDataIdField,
+  entityDataIdField, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -58,7 +58,7 @@ const TestEntity = cmp(function TestEntity(props: any) {
     return
   }
 
-  const PROJUPPER = nom(model.const, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJUPPER = envName(model)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -154,7 +154,7 @@ ${hasList ? `
     -- The basic flow consumes synthetic IDs from the fixture. In live mode
     -- without an *_ENTID env override, those IDs hit the live API and 4xx.
     if setup.synthetic_only then
-      pending("live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID JSON to run live")
+      pending("live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID JSON to run live")
       return
     end
     local client = setup.client
@@ -235,17 +235,17 @@ end)
     Content(`  -- Detect ENTID env override before envOverride consumes it. When live
   -- mode is on without a real override, the basic test runs against synthetic
   -- IDs from the fixture and 4xx's. Surface this so the test can skip.
-  local entid_env_raw = os.getenv("${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID")
+  local entid_env_raw = os.getenv("${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID")
   local idmap_overridden = entid_env_raw ~= nil and entid_env_raw:match("^%s*{") ~= nil
 
   local env = runner.env_override({
-    ["${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID"] = idmap,
+    ["${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID"] = idmap,
     ["${PROJUPPER}_TEST_LIVE"] = "FALSE",
     ["${PROJUPPER}_TEST_EXPLAIN"] = "FALSE",${apikeyEnvEntry}
   })
 
   local idmap_resolved = helpers.to_map(
-    env["${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID"])
+    env["${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID"])
   if idmap_resolved == nil then
     idmap_resolved = helpers.to_map(idmap)
   end
@@ -331,7 +331,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
   Content(`
     local ${datavar}_result, err = ${entvar}:create(${datavar}, nil)
     assert.is_nil(err)
-    ${datavar} = helpers.to_map(${datavar}_result)
+    ${datavar} = helpers.to_map(type(${datavar}_result) == 'table' and ${datavar}_result.data_get and ${datavar}_result:data_get() or ${datavar}_result)
     assert.is_not_nil(${datavar})
 `)
   if (null != ctx.entity.id) {
@@ -467,7 +467,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   Content(`
     local ${resdatavar}_result, err = ${entvar}:update(${datavar}_up, nil)
     assert.is_nil(err)
-    local ${resdatavar} = helpers.to_map(${resdatavar}_result)
+    local ${resdatavar} = helpers.to_map(type(${resdatavar}_result) == 'table' and ${resdatavar}_result.data_get and ${resdatavar}_result:data_get() or ${resdatavar}_result)
     assert.is_not_nil(${resdatavar})
 `)
   if (hasEntIdU) {
@@ -533,7 +533,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
     }
     local ${datavar}_loaded, err = ${entvar}:load(${matchvar}, nil)
     assert.is_nil(err)
-    local ${datavar}_load_result = helpers.to_map(${datavar}_loaded)
+    local ${datavar}_load_result = helpers.to_map(type(${datavar}_loaded) == 'table' and ${datavar}_loaded.data_get and ${datavar}_loaded:data_get() or ${datavar}_loaded)
     assert.is_not_nil(${datavar}_load_result)
     assert.are.equal(${datavar}_load_result["id"], ${srcdatavar}["id"])
 `)

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

@@ -23,6 +23,7 @@ function EntyClass.new(client, entopts)
   self._utility = client:get_utility()
   self._entopts = entopts
   self._data = {}
+  self._deleted = false
   self._match = {}
 
   self._entctx = self._utility.make_context({
@@ -50,6 +51,19 @@ function EntyClass:make()
 end
 
 
+-- Every operation resolves to the entity; `remove` additionally marks
+-- it. The instance KEEPS the data it held — a caller can still read what
+-- was deleted — but it is no longer a live record. See AGENTS.md.
+function EntyClass:mark_deleted()
+  self._deleted = true
+end
+
+
+function EntyClass:deleted()
+  return true == self._deleted
+end
+
+
 function EntyClass:data_set(args)
   if args ~= nil then
     self._data = helpers.to_map(vs.clone(args)) or {}
@@ -277,7 +291,29 @@ function EntyClass:_run_op(ctx, post_done)
 
   post_done()
 
-  return utility.done(ctx)
+  local out, done_err = utility.done(ctx)
+  if done_err ~= nil then
+    return out, done_err
+  end
+
+  -- An operation resolves to the ENTITY, not the raw data. Entities are
+  -- stateful: post_done has just absorbed resdata/resmatch into this
+  -- instance, and the caller reaches the record through data(). Two
+  -- structural exceptions: `list` resolves to the ARRAY of entity
+  -- instances make_result built, and a failed op with throwing disabled
+  -- hands back the error payload unchanged. `remove` additionally marks
+  -- the entity deleted; it KEEPS its data, so a caller can still read
+  -- what was removed. See AGENTS.md "Entity operations return ENTITIES".
+  local opname = ctx.op ~= nil and ctx.op.name or nil
+
+  if ctx.result ~= nil and ctx.result.ok and opname ~= "list" then
+    if opname == "remove" then
+      self:mark_deleted()
+    end
+    return self, nil
+  end
+
+  return out, nil
 end
 
 

package/project/.sdk/src/cmp/lua/fragment/SdkError.fragment.lua

@@ -9,10 +9,22 @@ function ProjectNameError.new(code, msg)
   self.code = code or ""
   self.msg = msg or ""
   self.sdk = "ProjectName"
+
+  -- HTTP status of the response that caused this error, or -1 when the
+  -- request never got one. PROMOTED to the top level: it used to be
+  -- reachable only at `err.result.status`, so every consumer coupled itself
+  -- to the internal shape of `result`.
+  self.status = -1
+
   return self
 end
 
 
+function ProjectNameError:not_found()
+  return 404 == self.status
+end
+
+
 function ProjectNameError:error()
   return self.sdk .. ": " .. self.code .. ": " .. self.msg
 end

package/project/.sdk/src/cmp/ocaml/EntityOperation_ocaml.ts

@@ -41,6 +41,33 @@ function entityOp(opname: string, present: boolean, entityname: string): string
     post = `            ()\n`
   }
 
+  // The op resolves to the ENTITY (see Sdk_types). `list` builds one entity
+  // per record here, since make_result works in `value` and cannot; `remove`
+  // marks the instance. With throwing disabled run_op returns the error
+  // payload, which an entity_obj return cannot carry, so that path resolves to
+  // the entity too and the caller reads ctrl.err - the mechanism no-throw mode
+  // documents anyway.
+  const tail =
+    'list' === opname
+      ? `      let out = run_op ctx post_done in
+      (match out with
+       | List items ->
+         List.map (fun entry ->
+             let e = ent.e_make () in
+             (match entry with Map _ -> e.e_data_set entry | _ -> ());
+             e)
+           !items
+       | _ -> []));
+`
+      : 'remove' === opname
+        ? `      ignore (run_op ctx post_done);
+      ent.e_mark_deleted ();
+      ent);
+`
+        : `      ignore (run_op ctx post_done);
+      ent);
+`
+
   return `  ent.${field} <- (fun ${arg} ctrl ->
       let ${arg} = if is_nullish ${arg} then empty_map () else ${arg} in
       let ctx = utility.u_make_context
@@ -50,11 +77,11 @@ function entityOp(opname: string, present: boolean, entityname: string): string
             cs_match = Some ent.e_match; cs_data = Some ent.e_data;
             ${inputField} = Some ${arg} }
           (Some entctx) in
-      run_op ctx (fun () ->
+      let post_done () =
           match ctx.c_result with
           | Some result ->
-${post}          | None -> ()));
-`
+${post}          | None -> () in
+${tail}`
 }
 
 

package/project/.sdk/src/cmp/ocaml/Entity_ocaml.ts

@@ -76,11 +76,16 @@ let rec make (client : sdk_client) (entopts_in : value) : entity_obj =
     e_data_get = (fun () -> empty_map ());
     e_match_set = (fun _ -> ());
     e_match_get = (fun () -> empty_map ());
-    e_load = (fun _ _ -> Noval);
-    e_list = (fun _ _ -> Noval);
-    e_create = (fun _ _ -> Noval);
-    e_update = (fun _ _ -> Noval);
-    e_remove = (fun _ _ -> Noval);
+    (* Placeholders: the real closures are installed below. They cannot name
+     * \`ent\` here, and the op signatures resolve to entity_obj, so failwith
+     * (which types as 'a) stands in. *)
+    e_load = (fun _ _ -> failwith "op not installed");
+    e_list = (fun _ _ -> failwith "op not installed");
+    e_create = (fun _ _ -> failwith "op not installed");
+    e_update = (fun _ _ -> failwith "op not installed");
+    e_remove = (fun _ _ -> failwith "op not installed");
+    e_deleted = false;
+    e_mark_deleted = (fun () -> ());
     e_stream = (fun _ _ _ -> Seq.empty);
   } in
   let entctx = utility.u_make_context
@@ -99,6 +104,7 @@ let rec make (client : sdk_client) (entopts_in : value) : entity_obj =
         utility.u_feature_hook entctx "SetMatch"
       end);
   ent.e_match_get <- (fun () -> utility.u_feature_hook entctx "GetMatch"; clone ent.e_match);
+  ent.e_mark_deleted <- (fun () -> ent.e_deleted <- true);
   (* Streaming operation. Runs \`action\` (an op name, e.g. "list") through the
    * full pipeline and returns a lazy Seq over result items, so the streaming
    * feature's incremental output is reachable (a normal op call materialises

package/project/.sdk/src/cmp/ocaml/Package_ocaml.ts

@@ -3,6 +3,7 @@ import {
   Content,
   File,
   cmp,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -15,6 +16,7 @@ import { packageName } from './utility_ocaml'
 // there is no depends list beyond the OCaml compiler.
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
+  const target = props.target
   const model = ctx$.model
 
   const pkg = packageName(model)
@@ -22,7 +24,7 @@ const Package = cmp(async function Package(props: any) {
   File({ name: pkg + '.opam' }, () => {
     Content(`opam-version: "2.0"
 name: "${pkg}"
-version: "0.0.1"
+version: "${packageVersion(model, target.name)}"
 synopsis: "${model.const.Name} SDK for OCaml (generated by @voxgig/sdkgen)"
 maintainer: "voxgig"
 authors: "voxgig"

package/project/.sdk/src/cmp/ocaml/ReadmeEntity_ocaml.ts

@@ -39,11 +39,11 @@ function ocamlType(type: any): string {
 // The op accessor spelling on the entity_obj record, plus a language-agnostic
 // description.
 const OP_DESC: Record<string, { method: string, desc: string }> = {
-  load:   { method: 'e_load reqmatch ctrl',   desc: 'Load a single entity by match criteria.' },
-  list:   { method: 'e_list reqmatch ctrl',   desc: 'List entities, optionally matching the given criteria.' },
-  create: { method: 'e_create reqdata ctrl',  desc: 'Create a new entity with the given data.' },
-  update: { method: 'e_update reqdata ctrl',  desc: 'Update an existing entity.' },
-  remove: { method: 'e_remove reqmatch ctrl', desc: 'Remove the matching entity.' },
+  load:   { method: 'e_load reqmatch ctrl',   desc: 'Load a single entity by match criteria. Resolves to the entity.' },
+  list:   { method: 'e_list reqmatch ctrl',   desc: 'List entities, optionally matching the given criteria. Resolves to one entity per record.' },
+  create: { method: 'e_create reqdata ctrl',  desc: 'Create a new entity with the given data. Resolves to the entity.' },
+  update: { method: 'e_update reqdata ctrl',  desc: 'Update an existing entity. Resolves to the entity.' },
+  remove: { method: 'e_remove reqmatch ctrl', desc: 'Remove the matching entity. Resolves to the entity, marked deleted.' },
 }
 
 
@@ -138,7 +138,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       Content(`#### Example: Load
 
 \`\`\`ocaml
+(* The op resolves to the ENTITY; the record is inside it. *)
 let ${fn} = (Sdk_client.${fn} client Noval).e_load (${loadArg}) Noval
+let ${fn}_data = ${fn}.e_data_get ()
 \`\`\`
 
 `)
@@ -148,7 +150,9 @@ let ${fn} = (Sdk_client.${fn} client Noval).e_load (${loadArg}) Noval
       Content(`#### Example: List
 
 \`\`\`ocaml
+(* One ENTITY per record. *)
 let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval
+let ${fn}_datas = List.map (fun e -> e.e_data_get ()) ${fn}s
 \`\`\`
 
 `)
@@ -167,6 +171,7 @@ let ${fn} = (Sdk_client.${fn} client Noval).e_create (jo [
 `)
       })
       Content(`]) Noval
+let ${fn}_data = ${fn}.e_data_get ()
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/ocaml/ReadmeHowto_ocaml.ts

@@ -53,9 +53,13 @@ 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. *)
+    ? ('list' === primaryOp
+      ? `(* Entity ops resolve to the ENTITY (list: one per record) and raise on error. *)
+  let ${fn}s = (Sdk_client.${fn} client Noval).${field} ${testArg} Noval in
+  List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) ${fn}s  (* the mock records *)`
+      : `(* Entity ops resolve to the ENTITY and raise on error. *)
   let ${fn} = (Sdk_client.${fn} client Noval).${field} ${testArg} Noval in
-  print_endline (stringify ${fn})  (* the mock response record *)`
+  print_endline (stringify (${fn}.e_data_get ()))  (* the mock response record *)`)
     : `let result = Sdk_client.direct client (jo [("path", Str "/api/resource"); ("method", Str "GET")]) in
   print_endline (stringify result)`
 

package/project/.sdk/src/cmp/ocaml/ReadmeModel_ocaml.ts

@@ -21,11 +21,11 @@ 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: '| `e_load` | `value -> value -> value` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `e_list` | `value -> value -> value` | List entities matching the criteria (returns a List). Raises on error. |',
-    create: '| `e_create` | `value -> value -> value` | Create a new entity. Raises on error. |',
-    update: '| `e_update` | `value -> value -> value` | Update an existing entity. Raises on error. |',
-    remove: '| `e_remove` | `value -> value -> value` | Remove an entity. Raises on error. |',
+    load: '| `e_load` | `value -> value -> entity_obj` | Load a single entity by match criteria. Resolves to the entity. Raises on error. |',
+    list: '| `e_list` | `value -> value -> entity_obj list` | List entities matching the criteria. Resolves to one entity per record. Raises on error. |',
+    create: '| `e_create` | `value -> value -> entity_obj` | Create a new entity. Resolves to the entity. Raises on error. |',
+    update: '| `e_update` | `value -> value -> entity_obj` | Update an existing entity. Resolves to the entity. Raises on error. |',
+    remove: '| `e_remove` | `value -> value -> entity_obj` | Remove an entity. Resolves to the entity, marked deleted. Raises on error. |',
   }
   const opRows = ['load', 'list', 'create', 'update', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
@@ -98,9 +98,11 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result value (a \`Map\` for single-entity
-ops, a \`List\` for \`e_list\`) and raise \`Sdk_error.E\` on error. Wrap calls
-in \`try\`/\`with\` to handle failures.
+Entity operations resolve to the ENTITY, not the raw record \u2014 \`e_list\` to
+one entity per record \u2014 and raise \`Sdk_error.E\` on error. The record is
+reached through \`e_data_get\`, which returns the entity's data container.
+\`e_remove\` resolves to the entity marked deleted (\`e_deleted\`); it keeps the
+data it held. Wrap calls in \`try\`/\`with\` to handle failures.
 
 The \`direct\` escape hatch never raises — it returns a result \`value\` map
 you branch on via \`getp result "ok"\`: