@voxgig/sdkgen 2.0.2 → 3.0.0

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

@@ -3,7 +3,7 @@ import {
   Content,
   File,
   cmp,
-  collectDeps,
+  collectDeps, goModule, goVersion
 } from '@voxgig/sdkgen'
 
 
@@ -18,14 +18,17 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
-  // Module name: concatenated lowercase (e.g., voxgigsolardemosdk)
-  // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
+  // Module path and language version both come from the model — see
+  // goModule / goVersion. Neither is derivable from the slug alone: the repo
+  // may not be named `<slug>-sdk`, and the hardcoded `go 1.20` this used to
+  // emit could not compile sdkgen's own `log` feature (it imports log/slog,
+  // which needs 1.21).
+  const gomodule = goModule(model, 'go')
 
   File({ name: 'go.mod' }, () => {
     Content(`module ${gomodule}
 
-go 1.20
+go ${goVersion(model, target.name)}
 
 `)
 

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

@@ -1,12 +1,12 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, goModule } from '@voxgig/sdkgen'
 
 
 const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
   const { target, ctx$: { model } } = props
 
   // 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')
 
   Content(`### Data as maps
 

package/project/.sdk/src/cmp/go/ReadmeHowto_go.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, goModule } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -29,7 +29,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   // 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')
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
   // Pick an entity with a real op (prefer a read op) — never fabricate a

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

@@ -8,7 +8,9 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
 
   // Go module path == repo path on GitHub (org from model.origin).
   const gomodule = packageName(model, 'go')
-  const { releasesUrl } = repoInfo(model)
+  // `repo` is the directory a `git clone` of this project creates — not
+  // `<slug>-sdk`, which is only the DEFAULT repo name.
+  const { releasesUrl, repo } = repoInfo(model)
 
   Content(`\`\`\`bash
 go get ${gomodule}@latest
@@ -22,7 +24,7 @@ project and add a \`replace\` directive pointing at the checked-out
 \`go/\` directory:
 
 \`\`\`bash
-go mod edit -replace ${gomodule}=../${model.name}-sdk/go
+go mod edit -replace ${gomodule}=../${repo}/go
 \`\`\`
 
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, entityIdField, entityPrimaryOp } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, entityIdField, entityPrimaryOp, goModule } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -44,7 +44,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const resultShapeRows = resultRows.join('\n')
 
   // 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')
 
   const apikeyOptionRow = isAuthActive(model)
     ? '| `"apikey"` | `string` | API key for authentication. |\n'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps, goModule } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -20,7 +20,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
   // 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')
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityOps, opRequestShape, goModule } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -15,7 +15,7 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
   // 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')
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, goModule } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -28,7 +28,7 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
   // 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')
 
   // Pick an entity with a real op (prefer a read op) — never fabricate a
   // `load` on an op-less entity like Cloudsmith's `Abort`.

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

@@ -11,7 +11,7 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken, liveStrict
 } from '@voxgig/sdkgen'
 
 
@@ -65,7 +65,11 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const entity: ModelEntity = props.entity
   const gomodule = props.gomodule
 
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJECTNAME = envName(model)
+
+  // Does a live run ASSERT, or merely observe? See helpers/testPolicy.
+  // t.Skipf passes; t.Fatalf does not.
+  const liveFail = liveStrict(model, target.name) ? 'Fatalf' : 'Skipf'
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -146,7 +150,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     : ''
 
   // Build the ENTID env var name for this entity
-  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 }, () => {
 
@@ -254,18 +258,19 @@ ${listSkipBlock}		client := setup.client
       }
 
       Content(`		if setup.live {
-			// Live mode is lenient: synthetic IDs frequently 4xx and the
-			// list-response shape varies wildly across public APIs. Skip
-			// rather than fail when the call doesn't return a usable list.
+			// Live-mode leniency is a model decision
+			// (main.kit.test.live.strict): synthetic IDs 4xx constantly
+			// against an arbitrary public API, so the default SKIPS here.
+			// A project that owns its test server sets strict and FAILS.
 			if err != nil {
-				t.Skipf("list call failed (likely synthetic IDs against live API): %v", err)
+				t.${liveFail}("list call failed (likely synthetic IDs against live API): %v", err)
 			}
 			if result["ok"] != true {
-				t.Skipf("list call not ok (likely synthetic IDs against live API): %v", result)
+				t.${liveFail}("list call not ok (likely synthetic IDs against live API): %v", result)
 			}
 			status := core.ToInt(result["status"])
 			if status < 200 || status >= 300 {
-				t.Skipf("expected 2xx status, got %v", result["status"])
+				t.${liveFail}("expected 2xx status, got %v", result["status"])
 			}
 		} else {
 			if err != nil {
@@ -413,10 +418,10 @@ ${loadSkipBlock}		client := setup.client
 				"params": listParams,
 			})
 			if listErr != nil {
-				t.Skipf("list call failed (likely synthetic IDs against live API): %v", listErr)
+				t.${liveFail}("list call failed (likely synthetic IDs against live API): %v", listErr)
 			}
 			if listResult["ok"] != true {
-				t.Skipf("list call not ok (likely synthetic IDs against live API): %v", listResult)
+				t.${liveFail}("list call not ok (likely synthetic IDs against live API): %v", listResult)
 			}
 
 			// Get first entity ID from list
@@ -468,16 +473,17 @@ ${loadSkipBlock}		client := setup.client
 		if setup.live {
 			// Live mode is lenient: synthetic IDs frequently 4xx. Skip
 			// rather than fail when the load endpoint isn't reachable with
-			// the IDs we can construct from setup.idmap.
+			// the IDs we can construct from setup.idmap — unless the model
+			// sets main.kit.test.live.strict.
 			if err != nil {
-				t.Skipf("load call failed (likely synthetic IDs against live API): %v", err)
+				t.${liveFail}("load call failed (likely synthetic IDs against live API): %v", err)
 			}
 			if result["ok"] != true {
-				t.Skipf("load call not ok (likely synthetic IDs against live API): %v", result)
+				t.${liveFail}("load call not ok (likely synthetic IDs against live API): %v", result)
 			}
 			status := core.ToInt(result["status"])
 			if status < 200 || status >= 300 {
-				t.Skipf("expected 2xx status, got %v", result["status"])
+				t.${liveFail}("expected 2xx status, got %v", result["status"])
 			}
 		} else {
 			if err != nil {

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)
 \`\`\`
 
 `)