@voxgig/sdkgen 2.0.2 → 3.1.0

package/project/.sdk/src/cmp/go/TestEntity_go.ts

@@ -24,7 +24,7 @@ import {
   buildIdNames,
   getMatchEntries,
   isAuthActive,
-  entityDataIdField,
+  entityDataIdField, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -67,7 +67,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
@@ -194,7 +194,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.syntheticOnly {
-			t.Skip("live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID JSON to run live")
+			t.Skip("live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID JSON to run live")
 			return
 		}
 ${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
@@ -281,16 +281,16 @@ ${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
 	// 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.
-	entidEnvRaw := os.Getenv("${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID")
+	entidEnvRaw := os.Getenv("${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID")
 	idmapOverridden := entidEnvRaw != "" && strings.HasPrefix(strings.TrimSpace(entidEnvRaw), "{")
 
 	env := envOverride(map[string]any{
-		"${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}
 	})
 
-	idmapResolved := core.ToMapAny(env["${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID"])
+	idmapResolved := core.ToMapAny(env["${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID"])
 	if idmapResolved == nil {
 		idmapResolved = core.ToMapAny(idmap)
 	}
@@ -381,7 +381,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 		if err != nil {
 			t.Fatalf("create failed: %v", err)
 		}
-		${datavar} = core.ToMapAny(${datavar}Result)
+		${datavar} = core.ToMapAny(entityData(${datavar}Result))
 		if ${datavar} == nil {
 			t.Fatal("expected create result to be a map")
 		}
@@ -546,7 +546,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 		if err != nil {
 			t.Fatalf("update failed: %v", err)
 		}
-		${resdatavar} := core.ToMapAny(${resdatavar}Result)
+		${resdatavar} := core.ToMapAny(entityData(${resdatavar}Result))
 		if ${resdatavar} == nil {
 			t.Fatal("expected update result to be a map")
 		}
@@ -621,7 +621,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
 		if err != nil {
 			t.Fatalf("load failed: %v", err)
 		}
-		${datavar}LoadResult := core.ToMapAny(${datavar}Loaded)
+		${datavar}LoadResult := core.ToMapAny(entityData(${datavar}Loaded))
 		if ${datavar}LoadResult == nil {
 			t.Fatal("expected load result to be a map")
 		}

package/project/.sdk/src/cmp/go/Test_go.ts

@@ -8,7 +8,7 @@ import type {
   ModelEntity
 } from '@voxgig/apidef'
 
-import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
+import { cmp, each, Folder, File, Content, goModule } from '@voxgig/sdkgen'
 
 
 import { TestEntity } from './TestEntity_go'
@@ -22,7 +22,7 @@ const Test = cmp(function Test(props: any) {
 
   // Module name: concatenated lowercase
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
+  const gomodule = goModule(model, 'go')
 
   Folder({ name: 'test' }, () => {
 

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

@@ -14,6 +14,7 @@ type EntyClass struct {
 	data    map[string]any
 	match   map[string]any
 	entctx  *core.Context
+	deleted bool
 }
 
 func NewEntyClass(client *core.ProjectNameSDK, entopts map[string]any) *EntyClass {
@@ -49,6 +50,21 @@ func NewEntyClass(client *core.ProjectNameSDK, entopts map[string]any) *EntyClas
 
 func (e *EntyClass) GetName() string { return e.name }
 
+// Deleted marks this instance as removed. `Remove` resolves to the entity
+// like every other operation, and 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 "Entity operations return ENTITIES".
+func (e *EntyClass) MarkDeleted() {
+	e.deleted = true
+}
+
+
+// Deleted reports whether a successful Remove has resolved on this instance.
+func (e *EntyClass) Deleted() bool {
+	return e.deleted
+}
+
+
 func (e *EntyClass) Make() core.Entity {
 	opts := map[string]any{}
 	for k, v := range e.entopts {
@@ -296,5 +312,30 @@ func (e *EntyClass) runOp(ctx *core.Context, postDone func()) (any, error) {
 
 	postDone()
 
-	return utility.Done(ctx)
+	out, doneErr := utility.Done(ctx)
+	if doneErr != nil {
+		return out, doneErr
+	}
+
+	// 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".
+	opname := ""
+	if ctx.Op != nil {
+		opname = ctx.Op.Name
+	}
+
+	if ctx.Result != nil && ctx.Result.Ok && opname != "list" {
+		if opname == "remove" {
+			e.MarkDeleted()
+		}
+		return e, nil
+	}
+
+	return out, nil
 }

package/project/.sdk/src/cmp/go-cli/Main_go-cli.ts

@@ -3,7 +3,7 @@ import * as Path from 'node:path'
 
 import {
   cmp, each, deriveEntityNames,
-  File, Content, Fragment, Slot,
+  File, Content, Fragment, Slot, goModule, goVersion
 } from '@voxgig/sdkgen'
 
 import type {
@@ -50,8 +50,8 @@ const Main = cmp(function Main(props: any) {
   const { model } = props.ctx$
 
   const org = model.origin || 'voxgig-sdk'
-  const sdkModule = `github.com/${org}/${model.name}-sdk/go`
-  const cliModule = `github.com/${org}/${model.name}-sdk/go-cli`
+  const sdkModule = goModule(model, 'go')
+  const cliModule = goModule(model, 'go-cli')
 
   const entityMap: any = getModelPath(model, `main.${KIT}.entity`)
   // Derive each entity's PascalCase `Name` here rather than relying on another
@@ -369,7 +369,7 @@ this repo, or upstream at
   // (go 1.24.7) — keep in step with BORU_ENG_VERSION.
   File({ name: 'go.mod' }, () => Content(`module ${cliModule}
 
-go 1.24.7
+go ${goVersion(model, 'go-cli', '1.24.7')}
 
 require ${sdkModule} v0.0.0
 require github.com/boru-lang/boru/eng/go ${BORU_ENG_VERSION}

package/project/.sdk/src/cmp/go-mcp/Main_go-mcp.ts

@@ -3,7 +3,7 @@ import * as Path from 'node:path'
 
 import {
   cmp, each, deriveEntityNames,
-  File, Content, Fragment, Slot,
+  File, Content, Fragment, Slot, goModule, goVersion
 } from '@voxgig/sdkgen'
 
 import type {
@@ -50,8 +50,8 @@ const Main = cmp(function Main(props: any) {
   const { model } = props.ctx$
 
   const org = model.origin || 'voxgig-sdk'
-  const sdkModule = `github.com/${org}/${model.name}-sdk/go`
-  const mcpModule = `github.com/${org}/${model.name}-sdk/go-mcp`
+  const sdkModule = goModule(model, 'go')
+  const mcpModule = goModule(model, 'go-mcp')
 
   const entityMap: any = getModelPath(model, `main.${KIT}.entity`)
   // Derive each entity's PascalCase `Name` here rather than relying on another
@@ -319,7 +319,7 @@ this repo, or upstream at
   // the public proxy. The MCP Go SDK requires go >= 1.25.
   File({ name: 'go.mod' }, () => Content(`module ${mcpModule}
 
-go 1.25.0
+go ${goVersion(model, 'go-mcp', '1.25.0')}
 
 require ${sdkModule} v0.0.0
 require github.com/modelcontextprotocol/go-sdk ${MCP_GO_SDK_VERSION}

package/project/.sdk/src/cmp/haskell/Package_haskell.ts

@@ -2,6 +2,7 @@ import {
   Content,
   File,
   cmp,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -28,7 +29,7 @@ const Package = cmp(async function Package(props: any) {
   File({ name: pkgName(model) + '.cabal' }, () => {
     Content(`cabal-version:      2.4
 name:               ${pkgName(model)}
-version:            0.0.1
+version:            ${packageVersion(model, target.name)}
 synopsis:           ${model.const.Name} SDK for Haskell (generated by @voxgig/sdkgen)
 license:            MIT
 build-type:         Simple

package/project/.sdk/src/cmp/haskell/ReadmeEntity_haskell.ts

@@ -33,11 +33,11 @@ function hsType(type: any): string {
 
 
 const OP_DESC: Record<string, { method: string, desc: string }> = {
-  load:   { method: 'eLoad ent match ctrl',   desc: 'Load a single entity by match criteria.' },
-  list:   { method: 'eList ent match ctrl',   desc: 'List entities, optionally matching the given criteria.' },
-  create: { method: 'eCreate ent data ctrl',  desc: 'Create a new entity with the given data.' },
-  update: { method: 'eUpdate ent data ctrl',  desc: 'Update an existing entity.' },
-  remove: { method: 'eRemove ent match ctrl', desc: 'Remove the matching entity.' },
+  load:   { method: 'eLoad ent match ctrl',   desc: 'Load a single entity by match criteria. Resolves to the entity.' },
+  list:   { method: 'eList ent match ctrl',   desc: 'List entities, optionally matching the given criteria. Resolves to one entity per record.' },
+  create: { method: 'eCreate ent data ctrl',  desc: 'Create a new entity with the given data. Resolves to the entity.' },
+  update: { method: 'eUpdate ent data ctrl',  desc: 'Update an existing entity. Resolves to the entity.' },
+  remove: { method: 'eRemove ent match ctrl', desc: 'Remove the matching entity. Resolves to the entity, marked deleted.' },
 }
 
 
@@ -133,6 +133,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   match <- jo ${loadArg}
   ctrl <- emptyMap
   ${eFn} <- Sdk.eLoad ent match ctrl
+  -- The op resolves to the ENTITY; the record is inside it.
+  ${eFn}Data <- Sdk.eDataGet ${eFn}
 \`\`\`
 
 `)
@@ -145,7 +147,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   ent <- Sdk.${eFn} sdk VNoval
   match <- emptyMap
   ctrl <- emptyMap
+  -- One ENTITY per record.
   ${eFn}s <- Sdk.eList ent match ctrl
+  ${eFn}Datas <- mapM Sdk.eDataGet ${eFn}s
 \`\`\`
 
 `)
@@ -168,6 +172,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       Content(`]
   ctrl <- emptyMap
   ${eFn} <- Sdk.eCreate ent d ctrl
+  ${eFn}Data <- Sdk.eDataGet ${eFn}
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/haskell/ReadmeModel_haskell.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: '| `eLoad` | `Value -> Value -> IO Value` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `eList` | `Value -> Value -> IO Value` | List entities matching the criteria. Raises on error. |',
-    create: '| `eCreate` | `Value -> Value -> IO Value` | Create a new entity. Raises on error. |',
-    update: '| `eUpdate` | `Value -> Value -> IO Value` | Update an existing entity. Raises on error. |',
-    remove: '| `eRemove` | `Value -> Value -> IO Value` | Remove an entity. Raises on error. |',
+    load: '| `eLoad` | `Value -> Value -> IO Entity` | Load a single entity by match criteria. Resolves to the entity. Raises on error. |',
+    list: '| `eList` | `Value -> Value -> IO [Entity]` | List entities matching the criteria. Resolves to one entity per record. Raises on error. |',
+    create: '| `eCreate` | `Value -> Value -> IO Entity` | Create a new entity. Resolves to the entity. Raises on error. |',
+    update: '| `eUpdate` | `Value -> Value -> IO Entity` | Update an existing entity. Resolves to the entity. Raises on error. |',
+    remove: '| `eRemove` | `Value -> Value -> IO Entity` | 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')
@@ -103,9 +103,11 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result \`Value\` (a map for single-entity
-ops, a list for \`eList\`) and raise on error. Wrap calls in
-\`Control.Exception.try\` to handle failures.
+Entity operations resolve to the ENTITY, not the raw record \u2014 \`eList\` to
+one entity per record \u2014 and raise on error. The record is reached through
+\`eDataGet\`, which returns the entity's data container. \`eRemove\` resolves to
+the entity marked deleted (\`eDeleted\`); it keeps the data it held. Wrap calls
+in \`Control.Exception.try\` to handle failures.
 
 The \`direct\` escape hatch never raises — it returns a result \`Value\`
 you branch on via its \`ok\` field (read with \`getp result "ok"\`):

package/project/.sdk/src/cmp/haskell/ReadmeQuick_haskell.ts

@@ -90,14 +90,15 @@ to recover from failures.
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`eList ent match ctrl\` returns a list \`Value\` and raises on error.
+\`eList ent match ctrl\` resolves to one ENTITY per record and raises on
+error. Read a record with \`eDataGet\`.
 
 \`\`\`haskell
   ent <- Sdk.${eFn} sdk VNoval
   match <- emptyMap
   ctrl <- emptyMap
   ${eFn}s <- Sdk.eList ent match ctrl
-  print ${eFn}s
+  mapM_ (\\en -> print =<< Sdk.eDataGet en) ${eFn}s
 \`\`\`
 
 `)
@@ -123,14 +124,15 @@ to recover from failures.
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`eLoad\` returns the bare record and raises on error.
+\`eLoad\` resolves to the ENTITY and raises on error; \`eDataGet\` gives the
+record.
 
 \`\`\`haskell
   ${neFn}Ent <- Sdk.${neFn} sdk VNoval
   m <- jo [${neMatch.join(', ')}]
   ctrl2 <- emptyMap
   ${neFn} <- Sdk.eLoad ${neFn}Ent m ctrl2
-  print ${neFn}
+  print =<< Sdk.eDataGet ${neFn}
 \`\`\`
 
 `)
@@ -148,14 +150,15 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`eLoad ent match ctrl\` returns the bare record and raises on error.
+\`eLoad ent match ctrl\` resolves to the ENTITY and raises on error;
+\`eDataGet\` gives the record.
 
 \`\`\`haskell
   ent2 <- Sdk.${eFn} sdk VNoval
   m <- jo ${loadArg}
   ctrl2 <- emptyMap
   ${eFn} <- Sdk.eLoad ent2 m ctrl2
-  print ${eFn}
+  print =<< Sdk.eDataGet ${eFn}
 \`\`\`
 
 `)
@@ -192,7 +195,7 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
   d <- jo [${examplePairs('create').join(', ')}]
   cctrl <- emptyMap
   created <- Sdk.eCreate createEnt d cctrl
-  print created
+  print =<< Sdk.eDataGet created
 \`\`\`
 
 `)
@@ -204,7 +207,7 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
   upd <- jo [${updatePairs.join(', ')}]
   uctrl <- emptyMap
   updated <- Sdk.eUpdate updateEnt upd uctrl
-  print updated
+  print =<< Sdk.eDataGet updated
 \`\`\`
 
 `)
@@ -221,8 +224,9 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
   removeEnt <- Sdk.${eFn} sdk VNoval
   rm <- jo [${removePairs.length ? removePairs.join(', ') : ''}]
   rctrl <- emptyMap
-  _ <- Sdk.eRemove removeEnt rm rctrl
-  return ()
+  -- Resolves to the entity, marked deleted; it keeps the data it held.
+  removed <- Sdk.eRemove removeEnt rm rctrl
+  print =<< readIORef (Sdk.eDeleted removed)
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/haskell/ReadmeRef_haskell.ts

@@ -33,29 +33,29 @@ function hsType(type: any): string {
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'eLoad ent match ctrl :: IO Value',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    sig: 'eLoad ent match ctrl :: IO Entity',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Resolves to the ENTITY (read the record with `eDataGet`) and raises on error.',
   },
   list: {
-    sig: 'eList ent match ctrl :: IO Value',
-    returns: 'a list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — pass an empty map to list all records. Returns a list `Value` and raises on error.',
+    sig: 'eList ent match ctrl :: IO [Entity]',
+    returns: 'one entity per record',
+    desc: 'List entities matching the given criteria. The match is optional \u2014 pass an empty map to list all records. Resolves to one ENTITY per record and raises on error.',
   },
   create: {
-    sig: 'eCreate ent data ctrl :: IO 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: 'eCreate ent data ctrl :: IO Entity',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Resolves to the ENTITY (read the record with `eDataGet`) and raises on error.',
   },
   update: {
-    sig: 'eUpdate ent data ctrl :: IO 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: 'eUpdate ent data ctrl :: IO Entity',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the ENTITY (read the record with `eDataGet`) and raises on error.',
   },
   remove: {
-    sig: 'eRemove ent match ctrl :: IO Value',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    sig: 'eRemove ent match ctrl :: IO Entity',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Resolves to the ENTITY, marked deleted (`eDeleted`); it keeps the data it held. Raises on error.',
   },
 }
 
@@ -278,7 +278,8 @@ ${info.desc}
   ent <- Sdk.${eFn} sdk VNoval
   match <- emptyMap
   ctrl <- emptyMap
-  results <- Sdk.eList ent match ctrl
+  results <- Sdk.eList ent match ctrl   -- one ENTITY per record
+  datas <- mapM Sdk.eDataGet results
 \`\`\`
 
 `)
@@ -297,7 +298,8 @@ ${info.desc}
             })
             Content(`]
   ctrl <- emptyMap
-  result <- Sdk.eCreate ent d ctrl
+  result <- Sdk.eCreate ent d ctrl   -- the ENTITY
+  d2 <- Sdk.eDataGet result
 \`\`\`
 
 `)
@@ -318,7 +320,8 @@ ${info.desc}
     [${updateLines}
     ]  -- fields to update
   ctrl <- emptyMap
-  result <- Sdk.eUpdate ent d ctrl
+  result <- Sdk.eUpdate ent d ctrl   -- the ENTITY
+  d2 <- Sdk.eDataGet result
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/haskell/ReadmeTopQuick_haskell.ts

@@ -63,12 +63,12 @@ main = do
 
     if (opnames.includes('list')) {
       Content(`
-  -- List all ${eName.toLowerCase()}s (returns a list Value, raises on error)
+  -- List all ${eName.toLowerCase()}s (one ENTITY per record, raises on error)
   ent <- Sdk.${eFn} sdk VNoval
   match <- emptyMap
   ctrl <- emptyMap
   ${eFn}s <- Sdk.eList ent match ctrl
-  print ${eFn}s
+  mapM_ (\\en -> print =<< Sdk.eDataGet en) ${eFn}s
 `)
     }
 
@@ -83,12 +83,12 @@ main = do
             it.name === idF ? 'example_id' : 'example_' + it.name)})`).join(', ')}]`
         : '[]'
       Content(`
-  -- Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+  -- Load a specific ${eName.toLowerCase()} (returns the ENTITY, raises on error)
   ent2 <- Sdk.${eFn} sdk VNoval
   m <- jo ${loadArg}
   ctrl2 <- emptyMap
   ${eFn} <- Sdk.eLoad ent2 m ctrl2
-  print ${eFn}
+  print =<< Sdk.eDataGet ${eFn}
 `)
     }
   }

package/project/.sdk/src/cmp/haskell/Test_haskell.ts

@@ -81,7 +81,10 @@ ${basicFn} c = do
     ent <- C.${fn} sdk VNoval
     em1 <- emptyMap; em2 <- emptyMap
     lst <- eList ent em1 em2
-    pure (islist lst)
+    -- \`list\` resolves to one ENTITY per record; the record is reached
+    -- through eDataGet. See AGENTS.md "Entity operations return ENTITIES".
+    ok <- mapM (\\en -> ismap <$> eDataGet en) lst
+    pure (all id ok)
 `
         }
         if (hasLoad) {
@@ -95,8 +98,9 @@ ${basicFn} c = do
       (id0 : _) -> do
         m <- jo [("id", VStr id0)]; ctrl <- emptyMap
         loaded <- eLoad ent m ctrl
-        lid <- getp loaded "id"
-        pure (ismap loaded && vstring lid == id0)
+        ld <- eDataGet loaded
+        lid <- getp ld "id"
+        pure (ismap ld && vstring lid == id0)
 `
         }
         if (hasCreate) {
@@ -106,8 +110,9 @@ ${basicFn} c = do
     d <- newRefData fixture "${e.name}"
     ctrl <- emptyMap
     created <- eCreate ent d ctrl
-    cid <- getp created "id"
-    pure (ismap created && not (isNoval cid))
+    cd <- eDataGet created
+    cid <- getp cd "id"
+    pure (ismap cd && not (isNoval cid))
 `
         }
         if (hasCreate && hasUpdate) {
@@ -117,12 +122,14 @@ ${basicFn} c = do
     d <- newRefData fixture "${e.name}"
     ctrl <- emptyMap
     created <- eCreate ent d ctrl
-    cid <- getp created "id"
+    cd <- eDataGet created
+    cid <- getp cd "id"
     upd <- jo [("id", cid), ("${updField}", VStr "UpdatedMark")]
     ctrl2 <- emptyMap
     updated <- eUpdate ent upd ctrl2
-    uv <- getp updated "${updField}"
-    pure (ismap updated && vstring uv == "UpdatedMark")
+    ud <- eDataGet updated
+    uv <- getp ud "${updField}"
+    pure (ismap ud && vstring uv == "UpdatedMark")
 `
         }
         if (hasCreate && hasRemove) {
@@ -132,10 +139,15 @@ ${basicFn} c = do
     d <- newRefData fixture "${e.name}"
     ctrl <- emptyMap
     created <- eCreate ent d ctrl
-    cid <- getp created "id"
+    cd <- eDataGet created
+    cid <- getp cd "id"
     rm <- jo [("id", cid)]; ctrl2 <- emptyMap
-    _ <- eRemove ent rm ctrl2
-    pure True
+    -- \`remove\` resolves to the entity, marked. It KEEPS the data it held.
+    removed <- eRemove ent rm ctrl2
+    gone <- readIORef (eDeleted removed)
+    rd <- eDataGet removed
+    rid <- getp rd "id"
+    pure (gone && vstring rid == vstring cid)
 `
         }
         // An op-less entity (no list/load/create — e.g. a bare path entity)

package/project/.sdk/src/cmp/java/Package_java.ts

@@ -4,6 +4,7 @@ import {
   File,
   cmp,
   collectDeps,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -51,7 +52,7 @@ const Package = cmp(async function Package(props: any) {
 
   <groupId>${groupId}</groupId>
   <artifactId>${artifactId}</artifactId>
-  <version>0.0.1</version>
+  <version>${packageVersion(model, target.name)}</version>
   <name>${model.const.Name} SDK</name>
   <description>${model.const.Name} client SDK for Java (generated by @voxgig/sdkgen).</description>
 

package/project/.sdk/src/cmp/java/ReadmeHowto_java.ts

@@ -51,7 +51,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 raise on error.
+    ? `// Entity ops return the ENTITY and raises on error;
+// call data() for the record.
 Object ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null);
 // ${eVar} holds the mock response record
 System.out.println(${eVar});`

package/project/.sdk/src/cmp/java/ReadmeInstall_java.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isPublished, repoInfo } from '@voxgig/sdkgen'
+import { cmp, Content, isPublished, repoInfo, packageVersion } from '@voxgig/sdkgen'
 
 import { mavenGroupId } from './utility_java'
 
@@ -18,7 +18,7 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
 <dependency>
   <groupId>${groupId}</groupId>
   <artifactId>${artifactId}</artifactId>
-  <version>0.0.1</version>
+  <version>${packageVersion(model, target.name)}</version>
 </dependency>
 \`\`\`
 

package/project/.sdk/src/cmp/java/ReadmeModel_java.ts

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

package/project/.sdk/src/cmp/java/ReadmeQuick_java.ts

@@ -123,7 +123,7 @@ catch (RuntimeException err) {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record (as \`Object\`) and raises on error.
+\`load()\` returns the ENTITY — call data() for the record — and raises on error.
 
 \`\`\`java
 try {
@@ -151,7 +151,7 @@ catch (RuntimeException err) {
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record (as \`Object\`) and raises on error.
+\`load()\` returns the ENTITY — call data() for the record — and raises on error.
 
 \`\`\`java
 try {
@@ -191,7 +191,7 @@ catch (RuntimeException err) {
 \`\`\`java
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record (as Object)
+        Content(`// Create — returns the ENTITY (call data() for the record)
 Object created = client.${accessor}(null).create(Map.of(${examplePairs('create').join(', ')}), null);
 
 `)