@voxgig/sdkgen 2.0.2 → 3.1.0

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.