@voxgig/sdkgen 2.0.2 → 3.0.0

package/project/.sdk/src/cmp/rust/Package_rust.ts

@@ -4,6 +4,7 @@ import {
   File,
   cmp,
   collectDeps,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -30,7 +31,7 @@ const Package = cmp(async function Package(props: any) {
   File({ name: 'Cargo.toml' }, () => {
     Content(`[package]
 name = "${crateName(model)}"
-version = "0.0.1"
+version = "${packageVersion(model, target.name)}"
 edition = "2021"
 description = "${model.const.Name} SDK for Rust (generated by @voxgig/sdkgen)"
 license = "MIT"

package/project/.sdk/src/cmp/rust/TestDirect_rust.ts

@@ -11,7 +11,7 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -63,7 +63,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const entity: ModelEntity = props.entity
   const rustcrate: string = props.rustcrate
 
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJECTNAME = envName(model)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -112,7 +112,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const listPath = listPoint ? normalizePathParams(listPoint.parts || [], listPoint?.args?.params || [], listPoint?.rename?.param) : ''
   const listParams = listPoint?.args?.params || []
 
-  const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
+  const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
   const evar = rustVarName(entity.name)
 

package/project/.sdk/src/cmp/rust/TestEntity_rust.ts

@@ -17,7 +17,7 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -51,8 +51,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
     return
   }
 
-  const PROJUPPER = nom(model.const, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
-  const ENTUPPER = entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJUPPER = envName(model)
+  const ENTUPPER = envToken(entity.name)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -351,7 +351,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
     let ${datavar}_result = ${entvar}
         .create(${datavar}.clone(), Value::Noval)
         .expect("create failed");
-    let ${datavar} = to_map(&${datavar}_result);
+    let ${datavar} = to_map(&${datavar}_result.data(None));
     assert!(
         matches!(${datavar}, Value::Map(_)),
         "expected create result to be a map"
@@ -403,10 +403,9 @@ const generateList: OpGen = (ctx, step, index) => {
     let ${listvar} = ${entvar}
         .list(${matchvar}.clone(), Value::Noval)
         .expect("list failed");
-    assert!(
-        matches!(${listvar}, Value::List(_)),
-        "expected list result to be an array"
-    );
+    // list resolves to one ENTITY per record; the flow asserts on the
+    // records, so map each through data().
+    let ${listvar} = ja(${listvar}.iter().map(|e| e.data(None)).collect::<Vec<Value>>());
 `)
 
   // Validators from step.valid.
@@ -507,7 +506,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
     let ${resdatavar}_result = ${entvar}
         .update(${datavar}_up.clone(), Value::Noval)
         .expect("update failed");
-    let ${resdatavar} = to_map(&${resdatavar}_result);
+    let ${resdatavar} = to_map(&${resdatavar}_result.data(None));
     assert!(
         matches!(${resdatavar}, Value::Map(_)),
         "expected update result to be a map"
@@ -586,7 +585,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
     let ${datavar}_loaded = ${entvar}
         .load(${matchvar}.clone(), Value::Noval)
         .expect("load failed");
-    let ${datavar}_load_result = to_map(&${datavar}_loaded);
+    let ${datavar}_load_result = to_map(&${datavar}_loaded.data(None));
     assert!(
         matches!(${datavar}_load_result, Value::Map(_)),
         "expected load result to be a map"
@@ -603,9 +602,10 @@ const generateLoad: OpGen = (ctx, step, index) => {
     let ${datavar}_loaded = ${entvar}
         .load(${matchvar}.clone(), Value::Noval)
         .expect("load failed");
+    // load resolves to the ENTITY; the record is reached through data().
     assert!(
-        !${datavar}_loaded.is_noval(),
-        "expected load result to be non-nil"
+        !${datavar}_loaded.data(None).is_noval(),
+        "expected load result to carry data"
     );
 `)
   }

package/project/.sdk/src/cmp/rust/fragment/Entity.fragment.rs

@@ -24,6 +24,8 @@ pub struct EntyClass {
     data: RefCell<Value>,
     mtch: RefCell<Value>,
     entctx: RefCell<Option<Rc<Context>>>,
+    // Set once a successful `remove` resolves on this instance.
+    deleted: RefCell<bool>,
 }
 
 impl EntyClass {
@@ -46,6 +48,7 @@ impl EntyClass {
             data: RefCell::new(Value::empty_map()),
             mtch: RefCell::new(Value::empty_map()),
             entctx: RefCell::new(None),
+            deleted: RefCell::new(false),
         });
 
         let entctx = e.utility.make_context(
@@ -71,6 +74,10 @@ impl EntyClass {
             .expect("entity context not initialised")
     }
 
+    // Runs the pipeline and returns the terminal result VALUE. The entity
+    // contract lives one level up, in the op methods below: they call this,
+    // then hand back the entity (see AGENTS.md). It is split that way because
+    // `Value` is a closed data union that cannot carry an entity.
     fn run_op(
         &self,
         ctx: &Rc<Context>,
@@ -232,6 +239,17 @@ impl Entity for EntyClass {
         self.name.clone()
     }
 
+    // `remove` resolves to the entity, marked. The instance KEEPS the data
+    // it held — a caller can still read what was deleted — but it is no
+    // longer a live record.
+    fn mark_deleted(&self) {
+        *self.deleted.borrow_mut() = true;
+    }
+
+    fn deleted(&self) -> bool {
+        *self.deleted.borrow()
+    }
+
     fn make(&self) -> Rc<dyn Entity> {
         let opts = Value::empty_map();
         if let Value::Map(m) = &self.entopts {

package/project/.sdk/src/cmp/rust/fragment/EntityCreateOp.fragment.rs

@@ -1,6 +1,6 @@
 // EJECT-START
 
-fn create(&self, reqdata: Value, ctrl: Value) -> Result<Value, ProjectNameError> {
+fn create(self: &Rc<Self>, reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ProjectNameError> {
     let ctx = self.utility.make_context(
         CtxSpec {
             opname: Some("create".to_string()),
@@ -23,7 +23,13 @@ fn create(&self, reqdata: Value, ctrl: Value) -> Result<Value, ProjectNameError>
                 };
             }
         }
-    })
+    })?;
+
+    // The operation resolves to THIS entity: `run_op` has just absorbed the
+    // result into it, and the caller reaches the record through `.data(None)`.
+    // See AGENTS.md "Entity operations return ENTITIES".
+
+    Ok(self.clone())
 }
 
 // EJECT-END

package/project/.sdk/src/cmp/rust/fragment/EntityListOp.fragment.rs

@@ -1,6 +1,6 @@
 // EJECT-START
 
-fn list(&self, reqmatch: Value, ctrl: Value) -> Result<Value, ProjectNameError> {
+fn list(self: &Rc<Self>, reqmatch: Value, ctrl: Value) -> Result<Vec<Rc<Self>>, ProjectNameError> {
     let ctx = self.utility.make_context(
         CtxSpec {
             opname: Some("list".to_string()),
@@ -13,14 +13,31 @@ fn list(&self, reqmatch: Value, ctrl: Value) -> Result<Value, ProjectNameError>
         Some(&self.ent_ctx()),
     );
 
-    self.run_op(&ctx, &|ctx| {
+    let out = self.run_op(&ctx, &|ctx| {
         if let Some(result) = ctx.result.borrow().clone() {
             let resmatch = result.borrow().resmatch.clone();
             if let Value::Map(_) = resmatch {
                 *self.mtch.borrow_mut() = resmatch;
             }
         }
-    })
+    })?;
+
+    // `list` resolves to one ENTITY per record. makeResult cannot build them
+    // here — it works in `Value`, which is a closed data union with no slot
+    // for an entity — so the op does, mirroring what the dynamic targets get
+    // from makeResult. See AGENTS.md "Entity operations return ENTITIES".
+    let mut items: Vec<Rc<Self>> = Vec::new();
+    if let Value::List(list) = &out {
+        for entry in list.borrow().iter() {
+            let ent = EntyClass::new(&self.client, vs::clone(&self.entopts));
+            if let Value::Map(_) = entry {
+                ent.data(Some(entry));
+            }
+            items.push(ent);
+        }
+    }
+
+    Ok(items)
 }
 
 // EJECT-END

package/project/.sdk/src/cmp/rust/fragment/EntityLoadOp.fragment.rs

@@ -1,6 +1,6 @@
 // EJECT-START
 
-fn load(&self, reqmatch: Value, ctrl: Value) -> Result<Value, ProjectNameError> {
+fn load(self: &Rc<Self>, reqmatch: Value, ctrl: Value) -> Result<Rc<Self>, ProjectNameError> {
     let ctx = self.utility.make_context(
         CtxSpec {
             opname: Some("load".to_string()),
@@ -29,7 +29,13 @@ fn load(&self, reqmatch: Value, ctrl: Value) -> Result<Value, ProjectNameError>
                 };
             }
         }
-    })
+    })?;
+
+    // The operation resolves to THIS entity: `run_op` has just absorbed the
+    // result into it, and the caller reaches the record through `.data(None)`.
+    // See AGENTS.md "Entity operations return ENTITIES".
+
+    Ok(self.clone())
 }
 
 // EJECT-END

package/project/.sdk/src/cmp/rust/fragment/EntityRemoveOp.fragment.rs

@@ -1,6 +1,6 @@
 // EJECT-START
 
-fn remove(&self, reqmatch: Value, ctrl: Value) -> Result<Value, ProjectNameError> {
+fn remove(self: &Rc<Self>, reqmatch: Value, ctrl: Value) -> Result<Rc<Self>, ProjectNameError> {
     let ctx = self.utility.make_context(
         CtxSpec {
             opname: Some("remove".to_string()),
@@ -29,7 +29,15 @@ fn remove(&self, reqmatch: Value, ctrl: Value) -> Result<Value, ProjectNameError
                 };
             }
         }
-    })
+    })?;
+
+    // The operation resolves to THIS entity: `run_op` has just absorbed the
+    // result into it, and the caller reaches the record through `.data(None)`.
+    // See AGENTS.md "Entity operations return ENTITIES". A removed entity
+    // keeps its data but is no longer a live record.
+    self.mark_deleted();
+
+    Ok(self.clone())
 }
 
 // EJECT-END

package/project/.sdk/src/cmp/rust/fragment/EntityUpdateOp.fragment.rs

@@ -1,6 +1,6 @@
 // EJECT-START
 
-fn update(&self, reqdata: Value, ctrl: Value) -> Result<Value, ProjectNameError> {
+fn update(self: &Rc<Self>, reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ProjectNameError> {
     let ctx = self.utility.make_context(
         CtxSpec {
             opname: Some("update".to_string()),
@@ -29,7 +29,13 @@ fn update(&self, reqdata: Value, ctrl: Value) -> Result<Value, ProjectNameError>
                 };
             }
         }
-    })
+    })?;
+
+    // The operation resolves to THIS entity: `run_op` has just absorbed the
+    // result into it, and the caller reaches the record through `.data(None)`.
+    // See AGENTS.md "Entity operations return ENTITIES".
+
+    Ok(self.clone())
 }
 
 // EJECT-END

package/project/.sdk/src/cmp/rust/fragment/SdkError.fragment.rs

@@ -11,6 +11,11 @@ pub struct ProjectNameError {
     // Cleaned snapshots attached by makeError (Noval until then).
     pub result: Value,
     pub spec: Value,
+    // HTTP status of the response that caused this error, or -1 when the
+    // request never got one. PROMOTED to the top level: it used to be
+    // reachable only inside `result`, so every consumer coupled itself to
+    // the internal shape of that snapshot.
+    pub status: i64,
 }
 
 impl ProjectNameError {
@@ -21,8 +26,13 @@ impl ProjectNameError {
             msg: msg.to_string(),
             result: Value::Noval,
             spec: Value::Noval,
+            status: -1,
         }
     }
+
+    pub fn not_found(&self) -> bool {
+        404 == self.status
+    }
 }
 
 impl std::fmt::Display for ProjectNameError {

package/project/.sdk/src/cmp/scala/ReadmeHowto_scala.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.
 val ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null)
 // ${eVar} holds the mock response record
 println(${eVar})`

package/project/.sdk/src/cmp/scala/ReadmeInstall_scala.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_scala'
 
@@ -15,13 +15,13 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
     Content(`Add the dependency with scala-cli:
 
 \`\`\`scala
-//> using dep "${groupId}:${artifactId}_3:0.0.1"
+//> using dep "${groupId}:${artifactId}_3:${packageVersion(model, target.name)}"
 \`\`\`
 
 Or, with sbt:
 
 \`\`\`scala
-libraryDependencies += "${groupId}" %% "${artifactId}" % "0.0.1"
+libraryDependencies += "${groupId}" %% "${artifactId}" % "${packageVersion(model, target.name)}"
 \`\`\`
 
 Or build from a source checkout — the SDK is a plain scala-cli project:

package/project/.sdk/src/cmp/scala/ReadmeModel_scala.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/scala/ReadmeQuick_scala.ts

@@ -123,7 +123,7 @@ catch {
       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.
 
 \`\`\`scala
 try {
@@ -151,7 +151,7 @@ catch {
 
       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.
 
 \`\`\`scala
 try {
@@ -191,7 +191,7 @@ catch {
 \`\`\`scala
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record (as Object)
+        Content(`// Create — returns the ENTITY (call data() for the record)
 val created = client.${accessor}(null).create(java.util.Map.of(${examplePairs('create').join(', ')}), null)
 
 `)

package/project/.sdk/src/cmp/scala/TestEntity_scala.ts

@@ -181,7 +181,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
   }
 
   Content(`      val ${datavar}Result = ${entvar}.create(${datavar}, null)
-      ${datavar} = Helpers.toMapAny(${datavar}Result)
+      ${datavar} = Helpers.toMapAny(${datavar}Result match { case e: SdkEntity => e.data(); case o => o })
       rep.check("${ENTLOWER}.create.map", ${datavar} != null, "expected create result to be a map")
 `)
   if (null != entityDataIdField(entity)) {
@@ -312,7 +312,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   }
 
   Content(`      val ${resdatavar}Result = ${entvar}.update(${datavar}Up, null)
-      val ${resdatavar} = Helpers.toMapAny(${resdatavar}Result)
+      val ${resdatavar} = Helpers.toMapAny(${resdatavar}Result match { case e: SdkEntity => e.data(); case o => o })
       rep.check("${ENTLOWER}.update.map", ${resdatavar} != null, "expected update result to be a map")
 `)
   if (hasDataId) {
@@ -369,7 +369,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
   if (hasDataId) {
     Content(`      ${matchvar}.put("id", ${srcdatavar}.get("id"))
       val ${datavar}Loaded = ${entvar}.load(${matchvar}, null)
-      val ${datavar}LoadResult = Helpers.toMapAny(${datavar}Loaded)
+      val ${datavar}LoadResult = Helpers.toMapAny(${datavar}Loaded match { case e: SdkEntity => e.data(); case o => o })
       rep.check("${ENTLOWER}.load.map", ${datavar}LoadResult != null, "expected load result to be a map")
       rep.eq("${ENTLOWER}.load.id", ${srcdatavar}.get("id"), ${datavar}LoadResult.get("id"))
 `)

package/project/.sdk/src/cmp/scala/fragment/EntityBase.fragment.scala

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

package/project/.sdk/src/cmp/swift/ReadmeHowto_swift.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 throw on error.
+    ? `// Entity ops return the ENTITY and throws on error;
+// call data() for the record.
 let ${eVar} = try client.${eName}().${primaryOp}(${testArg}, nil)
 // ${eVar} holds the mock response record
 print(${eVar})`

package/project/.sdk/src/cmp/swift/ReadmeInstall_swift.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isPublished, repoInfo } from '@voxgig/sdkgen'
+import { cmp, Content, isPublished, repoInfo, packageVersion } from '@voxgig/sdkgen'
 
 
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
@@ -11,7 +11,7 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
 
 \`\`\`swift
 dependencies: [
-    .package(url: "<repo-url>", from: "0.0.1"),
+    .package(url: "<repo-url>", from: "${packageVersion(model, target.name)}"),
 ],
 \`\`\`
 
@@ -39,7 +39,7 @@ your \`Package.swift\`:
 \`\`\`swift
 dependencies: [
     // From the git release tag:
-    .package(url: "<repo-url>", exact: "0.0.1"),
+    .package(url: "<repo-url>", exact: "${packageVersion(model, target.name)}"),
 ],
 \`\`\`
 

package/project/.sdk/src/cmp/swift/ReadmeModel_swift.ts

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

package/project/.sdk/src/cmp/swift/ReadmeQuick_swift.ts

@@ -125,7 +125,7 @@ catch {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record (a \`Value\`) and throws on error.
+\`load()\` returns the ENTITY — call data() for the record — and throws on error.
 
 \`\`\`swift
 do {
@@ -153,7 +153,7 @@ catch {
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record (a \`Value\`) and throws on error.
+\`load()\` returns the ENTITY — call data() for the record — and throws on error.
 
 \`\`\`swift
 do {
@@ -193,7 +193,7 @@ catch {
 \`\`\`swift
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record (a Value)
+        Content(`// Create — returns the ENTITY (call data() for the record)
 let created = try client.${accessor}().create(VMap([${examplePairs('create').join(', ')}]), nil)
 
 `)

package/project/.sdk/src/cmp/swift/fragment/EntityBase.fragment.swift

@@ -84,6 +84,20 @@ open class ProjectNameEntityBase: Entity {
     throw unsupportedOp("remove", name)
   }
 
+  // Every operation resolves to the entity; `remove` additionally marks
+  // it. The instance KEEPS the data it held — a caller can still read
+  // what was deleted — but it is no longer a live record. See AGENTS.md.
+  private var deletedFlag: Bool = false
+
+  public func markDeleted() {
+    self.deletedFlag = true
+  }
+
+  public func deleted() -> Bool {
+    return self.deletedFlag
+  }
+
+
   func runOp(_ ctx: Context, _ postDone: () -> Void) throws -> Value {
     // #PrePoint-Hook
 
@@ -134,7 +148,26 @@ open class ProjectNameEntityBase: Entity {
 
     postDone()
 
-    return try utility.done(ctx)
+    let out = try utility.done(ctx)
+
+    // An operation resolves to the ENTITY, not the raw data. Entities are
+    // stateful: postDone has just absorbed resdata/resmatch into this
+    // instance, and the caller reaches the record through data(). Two
+    // structural exceptions: `list` resolves to the ARRAY of entity
+    // instances makeResult built, and a failed op with throwing disabled
+    // hands back the error payload unchanged. `remove` additionally marks
+    // the entity deleted; it KEEPS its data, so a caller can still read
+    // what was removed. See AGENTS.md "Entity operations return ENTITIES".
+    let opname = ctx.op?.name
+
+    if let result = ctx.result, result.ok, "list" != opname {
+      if "remove" == opname {
+        self.markDeleted()
+      }
+      return .native(NativeRef(self))
+    }
+
+    return out
   }
 
   // Streaming operations. Runs `action` through the full pipeline and returns

package/project/.sdk/src/cmp/ts/EntityOperation_ts.ts

@@ -1,7 +1,8 @@
 
 import {
   cmp, camelify,
-  Content, Fragment
+  Content, Fragment,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 
@@ -32,6 +33,13 @@ const EntityOperation = cmp(function Operation(props: any) {
       SdkName: model.const.Name,
       EntityName: entity.Name,
       entityname: entity.name,
+
+      // The CLASS token. Operations resolve to the entity instance, so their
+      // declared return type must name the class — `Promise<PlanetEntity>`,
+      // not `Promise<Planet>` (the data interface). A signature that says
+      // the data type while the call resolves to an entity is a lie the
+      // compiler cannot catch; see AGENTS.md.
+      EntyClass: entityClassName(entity, entityCollection(model)),
       "['POINTS']": formatJson(entop.points, { margin: 6 }).trim(),
       '#Feature-Hook': ({ name, indent }: any) =>
         Content({ indent }, `

package/project/.sdk/src/cmp/ts/EntityTypes_ts.ts

@@ -21,7 +21,7 @@ import {
   File, Content,
 } from '@voxgig/sdkgen'
 
-import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames } from '@voxgig/sdkgen'
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames, opActions } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -108,6 +108,23 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
           Content(`  ${propKey(it.name)}${opt}: ${canonToType(it.type, LANG)}
 `)
         })
+
+        // Custom actions are selected with `$action` in the call's argument
+        // (see the Actions section of REFERENCE.md). Without it in the type,
+        // the ONLY documented way to reach those endpoints does not compile,
+        // and a TypeScript caller has to cast — which is how two of one API's
+        // six endpoints came to be unreachable from the typed interface.
+        const actions = opActions(ops[opname])
+        if (0 < actions.length) {
+          Content(`
+  // Selects a custom action instead of the plain ${opname}:
+  //   ${actions.map((a: any) => `'` + a.action + `'`).join(' | ')}
+  // The remaining keys are that action's own payload.
+  $action?: string
+  [action: string]: any
+`)
+        }
+
         Content(`}
 
 `)