@voxgig/sdkgen 2.0.2 → 3.1.0

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

@@ -66,15 +66,13 @@ let client = ${ctor}
     if (opnames.includes('list')) {
       Content(`### 2. List ${fn} records
 
-\`e_list\` returns a \`List\` value of records (each a \`Map\`) and raises on
-error — iterate it directly.
+\`e_list\` resolves to one ENTITY per record and raises on error. Read a
+record with \`e_data_get\`.
 
 \`\`\`ocaml
 (try
    let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
-   (match ${fn}s with
-    | List items -> List.iter (fun r -> print_endline (stringify r)) !items
-    | _ -> ())
+   List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) ${fn}s
  with Sdk_error.E err -> Printf.eprintf "list failed: %s\\n" (Sdk_error.message err))
 \`\`\`
 
@@ -103,12 +101,13 @@ error — iterate it directly.
       Content(`### 3. Load ${neArticle} ${neFn}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`e_load\` returns the bare record (a \`Map\`) and raises on error.
+\`e_load\` resolves to the ENTITY and raises on error; \`e_data_get\` gives the
+record.
 
 \`\`\`ocaml
 (try
    let ${neFn} = (Sdk_client.${neFn} client Noval).e_load (jo [${neMatch.join('; ')}]) Noval in
-   print_endline (stringify ${neFn})
+   print_endline (stringify (${neFn}.e_data_get ()))
  with Sdk_error.E err -> Printf.eprintf "load failed: %s\\n" (Sdk_error.message err))
 \`\`\`
 
@@ -127,12 +126,13 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 
       Content(`### 3. Load ${article} ${fn}
 
-\`e_load\` returns the bare record (a \`Map\`) and raises on error.
+\`e_load\` resolves to the ENTITY and raises on error; \`e_data_get\` gives the
+record.
 
 \`\`\`ocaml
 (try
    let ${fn} = (Sdk_client.${fn} client Noval).e_load (${loadArg}) Noval in
-   print_endline (stringify ${fn})
+   print_endline (stringify (${fn}.e_data_get ()))
  with Sdk_error.E err -> Printf.eprintf "load failed: %s\\n" (Sdk_error.message err))
 \`\`\`
 
@@ -167,9 +167,9 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 \`\`\`ocaml
 `)
       if (opnames.includes('create')) {
-        Content(`(* Create — returns the bare created record (a Map) *)
+        Content(`(* Create — resolves to the ENTITY; e_data_get gives the record *)
 let created = (Sdk_client.${fn} client Noval).e_create (jo [${examplePairs('create').join('; ')}]) Noval in
-ignore created;
+print_endline (stringify (created.e_data_get ()));
 
 `)
       }
@@ -188,8 +188,9 @@ ignore ((Sdk_client.${fn} client Noval).e_update (jo [${updatePairs.join('; ')}]
           .map((it: any) => it.name === idF
             ? `("${it.name}", ${idValueFor('remove')})`
             : `("${it.name}", ${ocamlLit(it.type, 'example_' + it.name)})`)
-        Content(`(* Remove *)
-ignore ((Sdk_client.${fn} client Noval).e_remove (${removePairs.length ? `jo [${removePairs.join('; ')}]` : 'Noval'}) Noval)
+        Content(`(* Remove — resolves to the entity, marked deleted; it keeps its data *)
+let removed = (Sdk_client.${fn} client Noval).e_remove (${removePairs.length ? `jo [${removePairs.join('; ')}]` : 'Noval'}) Noval in
+Printf.printf "deleted: %b\\n" removed.e_deleted
 `)
       }
       Content(`\`\`\`

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

@@ -36,29 +36,29 @@ function ocamlType(type: any): string {
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'e_load reqmatch ctrl : value',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    sig: 'e_load reqmatch ctrl : entity_obj',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
   },
   list: {
-    sig: 'e_list reqmatch ctrl : value',
-    returns: 'a List of entities',
-    desc: 'List entities matching the given criteria. The match is optional — pass `(empty_map ())` to list all records. Returns a List and raises on error.',
+    sig: 'e_list reqmatch ctrl : entity_obj list',
+    returns: 'one entity per record',
+    desc: 'List entities matching the given criteria. The match is optional \u2014 pass `(empty_map ())` to list all records. Resolves to one ENTITY per record and raises on error.',
   },
   create: {
-    sig: 'e_create reqdata ctrl : value',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    sig: 'e_create reqdata ctrl : entity_obj',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
   },
   update: {
-    sig: 'e_update reqdata ctrl : value',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+    sig: 'e_update reqdata ctrl : entity_obj',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
   },
   remove: {
-    sig: 'e_remove reqmatch ctrl : value',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    sig: 'e_remove reqmatch ctrl : entity_obj',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Resolves to the ENTITY, marked deleted (`e_deleted`); it keeps the data it held. Raises on error.',
   },
 }
 
@@ -273,16 +273,16 @@ ${info.desc}
               : 'Noval'
             Content(`\`\`\`ocaml
 let result = (Sdk_client.${fn} client Noval).${'load' === opname ? 'e_load' : 'e_remove'} (${arg}) Noval
+let result_data = result.e_data_get ()
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`ocaml
+(* One ENTITY per record; the record is reached with e_data_get. *)
 let results = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
-(match results with
- | List items -> List.iter (fun r -> print_endline (stringify r)) !items
- | _ -> ())
+List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) results
 \`\`\`
 
 `)
@@ -298,6 +298,7 @@ let result = (Sdk_client.${fn} client Noval).e_create (jo [
 `)
             })
             Content(`]) Noval
+let result_data = result.e_data_get ()
 \`\`\`
 
 `)
@@ -314,6 +315,7 @@ let result = (Sdk_client.${fn} client Noval).e_create (jo [
 let result = (Sdk_client.${fn} client Noval).e_update (jo [
 ${updateLines}    (* Fields to update *)
 ]) Noval
+let result_data = result.e_data_get ()
 \`\`\`
 
 `)

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

@@ -49,9 +49,9 @@ let () =
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`  (* List all ${fn} records (returns a List value; raises on error) *)
+      Content(`  (* List all ${fn} records (one ENTITY per record; raises on error) *)
   let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
-  (match ${fn}s with List items -> List.iter (fun r -> print_endline (stringify r)) !items | _ -> ());
+  List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) ${fn}s;
 `)
     }
 
@@ -68,9 +68,9 @@ let () =
           `("${it.name}", ${ocamlLit(it.type,
             it.name === idF ? 'example_id' : 'example_' + it.name)})`).join('; ')}]`
         : 'Noval'
-      Content(`  (* Load a specific ${fn} (returns the record; raises on error) *)
+      Content(`  (* Load a specific ${fn} (returns the ENTITY; raises on error) *)
   let ${fn} = (Sdk_client.${fn} client Noval).e_load (${loadArg}) Noval in
-  print_endline (stringify ${fn})
+  print_endline (stringify (${fn}.e_data_get ()))
 `)
     }
   }

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

@@ -63,8 +63,14 @@ let () =
       const chosen = required.length ? required : items.slice(0, 3)
       arg = `(jo [${chosen.map((it: any) => `("${it.name}", ${ocamlLit(it.type)})`).join('; ')}])`
     }
-    Content(`  let result = (Sdk_client.${fn} client Noval).${field} ${arg} Noval in
-  print_endline (stringify result)
+    // The op resolves to the ENTITY (list: one per record); the record is
+    // reached with e_data_get.
+    Content('list' === primaryOp
+      ? `  let results = (Sdk_client.${fn} client Noval).${field} ${arg} Noval in
+  List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) results
+`
+      : `  let result = (Sdk_client.${fn} client Noval).${field} ${arg} Noval in
+  print_endline (stringify (result.e_data_get ()))
 `)
   }
 

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

@@ -53,17 +53,20 @@ let () =
       ignore ent;
 `)
       if (hasList) {
-        Content(`      let listed = ent.e_list (empty_map ()) Noval in
-      check "list is a list" (islist listed);
-      check_int "list size" (size listed) 1;
+        Content(`      (* The op resolves to one ENTITY per record; the record is reached
+         with e_data_get. See AGENTS.md "Entity operations return ENTITIES". *)
+      let listed = ent.e_list (empty_map ()) Noval in
+      check_int "list size" (List.length listed) 1;
+      List.iter (fun en -> check "list entry data is a map" (ismap (en.e_data_get ()))) listed;
 `)
       }
       if (hasLoad) {
         Content(`      let loaded = ent.e_load (jo [("id", Str "${ocamlString(id)}")]) Noval in
-      check "load is a map" (ismap loaded);
+      let loaded_data = loaded.e_data_get () in
+      check "load data is a map" (ismap loaded_data);
 `)
         if (hasId) {
-          Content(`      check_vstr "load id" (getp loaded "id") "${ocamlString(id)}";
+          Content(`      check_vstr "load id" (getp loaded_data "id") "${ocamlString(id)}";
 `)
         }
       }

package/project/.sdk/src/cmp/perl/ReadmeHowto_perl.ts

@@ -46,7 +46,8 @@ 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 die on error.
+    ? `# Entity ops return the ENTITY and dies on error;
+// call data_get for the record.
 my $${eVar} = $client->${eName}->${primaryOp}(${testArg});
 # $${eVar} contains the mock response record`
     : `my $result = $client->direct({ 'path' => '/api/resource', 'method' => 'GET' });

package/project/.sdk/src/cmp/perl/ReadmeModel_perl.ts

@@ -93,7 +93,7 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (a \`hashref\` for single-entity
+Entity operations return the ENTITY (call data_get for the record) (a \`hashref\` for single-entity
 ops, an \`arrayref\` for \`list\`) and die on error. Wrap calls in
 \`eval { ... }\` and inspect \`$@\` to handle failures.
 

package/project/.sdk/src/cmp/perl/ReadmeQuick_perl.ts

@@ -106,7 +106,7 @@ else {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record (a \`hashref\`) and dies on error.
+\`load()\` returns the ENTITY — call data_get for the record — and dies on error.
 
 \`\`\`perl
 my $${neVar} = eval { $client->${neName}->load({ ${neMatch.join(', ')} }) };
@@ -133,7 +133,7 @@ else {
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record (a \`hashref\`) and dies on error.
+\`load()\` returns the ENTITY — call data_get for the record — and dies on error.
 
 \`\`\`perl
 my $${eVar} = eval { $client->${eName}->load(${loadArg}) };
@@ -178,7 +178,7 @@ else {
 \`\`\`perl
 `)
       if (opnames.includes('create')) {
-        Content(`# Create — returns the bare created record (a hashref)
+        Content(`# Create — returns the ENTITY (call data_get for the record)
 my $created = $client->${eName}->create({ ${examplePairs('create').join(', ')} });
 
 `)

package/project/.sdk/src/cmp/perl/ReadmeTopQuick_perl.ts

@@ -73,7 +73,7 @@ for my $${eVar} (@$${eVar}s) {
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
         : ''
       Content(`
-# Load a specific ${eName.toLowerCase()} (returns the bare record; dies on error)
+# Load a specific ${eName.toLowerCase()} (returns the ENTITY; call data_get for the record; dies on error)
 my $${eVar} = $client->${eName}->load(${loadArg});
 print "$${eVar}->{id}\\n";
 `)

package/project/.sdk/src/cmp/perl/TestDirect_perl.ts

@@ -11,7 +11,7 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -70,7 +70,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const entity: ModelEntity = props.entity
 
   const N = model.const.Name
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJECTNAME = envName(model)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -132,7 +132,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     ? loadParams.map((p: any) => `    $params->{'${p.name}'} = ${perlScalar(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.t' }, () => {
 

package/project/.sdk/src/cmp/perl/TestEntity_perl.ts

@@ -17,7 +17,7 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -48,8 +48,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
   }
 
   const N = model.const.Name
-  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 ENTIDVAR = `${PROJUPPER}_TEST_${ENTUPPER}_ENTID`
 
   const authActive = isAuthActive(model)
@@ -263,7 +263,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
   Content(`
   $V{${datavar}_result} = $V{${entvar}}->create($V{${datavar}}, undef);
-  $V{${datavar}} = ${N}Helpers::to_map($V{${datavar}_result});
+  $V{${datavar}} = ${N}Helpers::to_map(ref($V{${datavar}_result}) && $V{${datavar}_result}->can('data_get') ? $V{${datavar}_result}->data_get : $V{${datavar}_result});
   ok(defined $V{${datavar}}, '${entity.name} create: data');
 `)
   if (null != ctx.entity.id) {
@@ -395,7 +395,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
   Content(`
   $V{${resdatavar}_result} = $V{${entvar}}->update($V{${datavar}_up}, undef);
-  $V{${resdatavar}} = ${N}Helpers::to_map($V{${resdatavar}_result});
+  $V{${resdatavar}} = ${N}Helpers::to_map(ref($V{${resdatavar}_result}) && $V{${resdatavar}_result}->can('data_get') ? $V{${resdatavar}_result}->data_get : $V{${resdatavar}_result});
   ok(defined $V{${resdatavar}}, '${entity.name} update: data');
 `)
   if (hasEntIdU) {
@@ -460,7 +460,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
     'id' => $V{${srcdatavar}}{id},
   };
   $V{${datavar}_loaded} = $V{${entvar}}->load($V{${matchvar}}, undef);
-  $V{${datavar}_load_result} = ${N}Helpers::to_map($V{${datavar}_loaded});
+  $V{${datavar}_load_result} = ${N}Helpers::to_map(ref($V{${datavar}_loaded}) && $V{${datavar}_loaded}->can('data_get') ? $V{${datavar}_loaded}->data_get : $V{${datavar}_loaded});
   ok(defined $V{${datavar}_load_result}, '${entity.name} load: data');
   is($V{${datavar}_load_result}{id}, $V{${srcdatavar}}{id}, '${entity.name} load: id');
 `)

package/project/.sdk/src/cmp/perl/fragment/Entity.fragment.pm

@@ -33,6 +33,7 @@ sub new {
     _utility => $client->get_utility,
     _entopts => $entopts,
     _data => {},
+    _deleted => 0,
     _match => {},
   }, $class;
 
@@ -57,6 +58,22 @@ sub make {
   return EntyClass->new($self->{_client}, $opts);
 }
 
+# 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.
+sub mark_deleted {
+  my ($self) = @_;
+  $self->{_deleted} = 1;
+  return $self;
+}
+
+
+sub deleted {
+  my ($self) = @_;
+  return $self->{_deleted} ? 1 : 0;
+}
+
+
 sub data_set {
   my ($self, $args) = @_;
   if ($args) {
@@ -222,7 +239,25 @@ sub _run_op {
 
     $post_done->();
 
-    $utility->{done}->($ctx);
+    my $out = $utility->{done}->($ctx);
+
+    # 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".
+    my $opname = $ctx->{op} ? $ctx->{op}{name} : undef;
+
+    if ($ctx->{result} && $ctx->{result}{ok}
+      && (!defined $opname || $opname ne 'list')) {
+      $self->mark_deleted if defined $opname && $opname eq 'remove';
+      return $self;
+    }
+
+    $out;
   };
   if (my $operr = $@) {
     # #PreUnexpected-Hook

package/project/.sdk/src/cmp/php/MainEntity_php.ts

@@ -1,6 +1,9 @@
 
 
-import { cmp, Content, entityClassName, entityCollection } from '@voxgig/sdkgen'
+import {
+  cmp, Content, entityClassName, entityCollection,
+  phpEntityAccessor, entityCacheField,
+} from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,12 +11,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Reserved PHP method names on the SDK class that an entity accessor must
-// not collide with. PHP method names are case-insensitive at declaration
-// time, so an entity literally named 'test' would collide with the static
-// `test()` test-mode constructor. Mangle to `<Name>_` in that case.
-const PHP_RESERVED_LOWER = new Set(['test'])
-
 const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
   const { model } = props.ctx$
@@ -28,24 +25,32 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   // a convenience — we declare it ONCE under the PascalCase name. An entity
   // literally named 'test' would collide (case-insensitively) with the static
   // `test()` test-mode constructor, so mangle to `<Name>_` in that case.
-  const accessor = PHP_RESERVED_LOWER.has(entity.name.toLowerCase())
-    ? entity.Name + '_'
-    : entity.Name
+  const accessor = phpEntityAccessor(entity.Name)
+
+  // The backing field is mangled independently of the accessor: the two are
+  // compared against different member sets, and an entity can collide with
+  // one without colliding with the other.
+  const field = entityCacheField(entity.name)
 
   Content(`
-    private $_${entity.name} = null;
+    private $_${field} = null;
 
-    // Canonical facade: $client->${accessor}()->list() / ->load(["id" => ...]).
+    // Canonical facade: $client->${accessor}()->list() / ->load(["id" => ...]).${
+      accessor === entity.Name
+        ? `
     // PHP method names are case-insensitive, so lowercase $client->${entity.name}()
-    // resolves here too.
+    // resolves here too.`
+        : `
+    // Renamed from ${entity.Name}: that name is already taken by an SDK class
+    // member, and a duplicate declaration is a fatal PHP parse error.`}
     public function ${accessor}($data = null)
     {
         require_once __DIR__ . '/entity/${entity.name}_entity.php';
         if ($data === null) {
-            if ($this->_${entity.name} === null) {
-                $this->_${entity.name} = new ${cls}($this, null);
+            if ($this->_${field} === null) {
+                $this->_${field} = new ${cls}($this, null);
             }
-            return $this->_${entity.name};
+            return $this->_${field};
         }
         return new ${cls}($this, $data);
     }

package/project/.sdk/src/cmp/php/Package_php.ts

@@ -6,7 +6,7 @@ import {
   collectDeps,
   pkgDescription,
   keywords,
-  repoInfo,
+  repoInfo, packageName
 } from '@voxgig/sdkgen'
 
 
@@ -32,7 +32,7 @@ const Package = cmp(async function Package(props: any) {
   // Generate composer.json
   File({ name: 'composer.json' }, () => {
     Content(`{
-  "name": "${ns}/${pkgBase}",
+  "name": "${packageName(model, 'php')}",
   "description": "${pkgDescription(model, 'php')}",
   "type": "library",
   "keywords": [${kw}],

package/project/.sdk/src/cmp/php/ReadmeEntity_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -68,7 +68,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`$${entity.name} = $client->${entity.Name}();\`
+    Content(`Create an instance: \`$${entity.name} = $client->${phpEntityAccessor(entity.Name)}();\`
 
 `)
 
@@ -123,8 +123,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       Content(`#### Example: Load
 
 \`\`\`php
-// load() returns the bare ${entity.Name} record (throws on error).
-$${entity.name} = $client->${entity.Name}()->load(${loadArg});
+// load() returns the ENTITY — call data_get() for the ${entity.Name} record (throws on error).
+$${entity.name} = $client->${phpEntityAccessor(entity.Name)}()->load(${loadArg});
 \`\`\`
 
 `)
@@ -135,7 +135,7 @@ $${entity.name} = $client->${entity.Name}()->load(${loadArg});
 
 \`\`\`php
 // list() returns an array of ${entity.Name} records (throws on error).
-$${entity.name}s = $client->${entity.Name}()->list();
+$${entity.name}s = $client->${phpEntityAccessor(entity.Name)}()->list();
 \`\`\`
 
 `)
@@ -150,7 +150,7 @@ $${entity.name}s = $client->${entity.Name}()->list();
       Content(`#### Example: Create
 
 \`\`\`php
-$${entity.name} = $client->${entity.Name}()->create([
+$${entity.name} = $client->${phpEntityAccessor(entity.Name)}()->create([
 `)
       createItems.map((it: any) => {
         Content(`    "${it.name}" => null, // ${canonToType(it.type, target.name)}

package/project/.sdk/src/cmp/php/ReadmeHowto_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
 
 import { KIT, getModelPath, nom } from '@voxgig/apidef'
 
@@ -51,8 +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 mock record (throws on error).
-$${eName.toLowerCase()} = $client->${eName}()->${primaryOp}(${testCallArg});
+    ? `// Entity ops return the ENTITY (throws on error);
+// call data_get() for the mock record.
+$${eName.toLowerCase()} = $client->${phpEntityAccessor(eName)}()->${primaryOp}(${testCallArg});
 print_r($${eName.toLowerCase()});`
     : `$result = $client->direct(["path" => "/api/resource", "method" => "GET"]);
 print_r($result);`

package/project/.sdk/src/cmp/php/ReadmeIntro_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, phpEntityAccessor } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -34,7 +34,7 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const opList = (opnames.length > 0 ? opnames : ['list', 'load']).join('`/`')
 
   const semantic = eName
-    ? `The SDK exposes the API as capitalised, semantic **Entities** — for example \`$client->${eName}()\` — with named operations (\`${opList}\`) instead of raw URL paths and query strings. Working with resources and verbs keeps call sites self-describing and reduces cognitive load.
+    ? `The SDK exposes the API as capitalised, semantic **Entities** — for example \`$client->${phpEntityAccessor(eName)}()\` — with named operations (\`${opList}\`) instead of raw URL paths and query strings. Working with resources and verbs keeps call sites self-describing and reduces cognitive load.
 
 `
     : ''

package/project/.sdk/src/cmp/php/ReadmeModel_php.ts

@@ -93,7 +93,7 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (an \`array\` for single-entity
+Entity operations return the ENTITY (call data_get() for the record) (an \`array\` for single-entity
 ops, a \`list\` for \`list\`) and throw on error. Wrap calls in
 \`try\`/\`catch\` to handle failures.