@voxgig/sdkgen 2.0.2 → 3.0.0

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"\`:

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