@voxgig/sdkgen 2.0.2 → 3.0.0

package/project/.sdk/src/cmp/cpp/TestEntity_cpp.ts

@@ -16,7 +16,7 @@ import {
   cmp,
   each,
   buildIdNames,
-  getMatchEntries,
+  getMatchEntries, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -43,7 +43,7 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const entity: ModelEntity = props.entity
 
   const ProjectName = model.const.Name
-  const PROJUPPER = nom(model.const, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJUPPER = envName(model)
 
   const basicflow: ModelEntityFlow | undefined =
     getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
@@ -111,12 +111,12 @@ static ${entity.Name}Setup ${evar}_basic_setup(const Value& extra) {
   if (!idmap.is_map()) idmap = vmap();
 
   Value env = env_override(vmap({
-    {"${PROJUPPER}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID", idmap},
+    {"${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID", idmap},
     {"${PROJUPPER}_TEST_LIVE", Value("FALSE")},
     {"${PROJUPPER}_TEST_EXPLAIN", Value("FALSE")}
   }));
 
-  Value idmap_resolved = Helpers::toMapAny(getp(env, "${PROJUPPER}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID"));
+  Value idmap_resolved = Helpers::toMapAny(getp(env, "${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID"));
   if (!idmap_resolved.is_map()) idmap_resolved = idmap;
 `)
 
@@ -264,7 +264,7 @@ const generateCreate: OpGen = (ctx, step: any, index) => {
   }
 
   Content(`  {
-    Value ${datavar}_result = ${entvar}->create(Struct::clone(${datavar}), Value::undef());
+    Value ${datavar}_result = ${entvar}->create(Struct::clone(${datavar}), Value::undef())->data();
     ${datavar} = Helpers::toMapAny(${datavar}_result);
     if (!${datavar}.is_map()) ${datavar} = vmap();
     ASSERT_TRUE(${datavar}.is_map(), "expected create result to be a map");
@@ -302,7 +302,10 @@ const generateList: OpGen = (ctx, step: any, index) => {
     Content(`  setp(${matchvar}, "${key}", getp(setup.idmap, "${val}"));
 `)
   }
-  Content(`  Value ${listvar} = ${entvar}->list(Struct::clone(${matchvar}), Value::undef());
+  Content(`  auto ${listvar}_ents = ${entvar}->list(Struct::clone(${matchvar}), Value::undef());
+  // list resolves to one ENTITY per record; the flow asserts on the records.
+  Value ${listvar} = vlist();
+  for (const auto& e : ${listvar}_ents) { ${listvar}.as_list()->push_back(e->data()); }
   ASSERT_TRUE(${listvar}.is_list(), "expected list result to be an array");
 `)
 
@@ -378,7 +381,7 @@ const generateUpdate: OpGen = (ctx, step: any, index) => {
       }
     }
   }
-  Content(`  Value ${resdatavar}_result = ${entvar}->update(Struct::clone(${datavar}_up), Value::undef());
+  Content(`  Value ${resdatavar}_result = ${entvar}->update(Struct::clone(${datavar}_up), Value::undef())->data();
   Value ${resdatavar} = Helpers::toMapAny(${resdatavar}_result);
   if (!${resdatavar}.is_map()) ${resdatavar} = vmap();
   ASSERT_TRUE(${resdatavar}.is_map(), "expected update result to be a map");
@@ -415,14 +418,14 @@ const generateLoad: OpGen = (ctx, step: any, index) => {
   }
   if (hasEntId) {
     Content(`  Value ${matchvar} = vmap({{"id", getp(${srcdatavar}, "id")}});
-  Value ${datavar}_loaded = ${entvar}->load(Struct::clone(${matchvar}), Value::undef());
+  Value ${datavar}_loaded = ${entvar}->load(Struct::clone(${matchvar}), Value::undef())->data();
   Value ${datavar}_load_result = Helpers::toMapAny(${datavar}_loaded);
   ASSERT_TRUE(${datavar}_load_result.is_map(), "expected load result to be a map");
   ASSERT_EQ_VAL(getp(${datavar}_load_result, "id"), getp(${srcdatavar}, "id"), "expected load result id to match");
 `)
   } else {
     Content(`  Value ${matchvar} = vmap();
-  Value ${datavar}_loaded = ${entvar}->load(${matchvar}, Value::undef());
+  Value ${datavar}_loaded = ${entvar}->load(${matchvar}, Value::undef())->data();
   ASSERT_TRUE(!${datavar}_loaded.is_undef(), "expected load result to be non-nil");
 `)
   }

package/project/.sdk/src/cmp/cpp/fragment/EntityCreateOp.fragment.cpp

@@ -1,6 +1,6 @@
 // EJECT-START
 
-  Value create(const Value& reqdata, const Value& ctrl) override {
+  SdkEntityPtr create(const Value& reqdata, const Value& ctrl) override {
     CtxSpec cs;
     cs.setOpname("create");
     cs.ctrlMap = ctrl.is_map() ? ctrl : vmap();
@@ -9,7 +9,7 @@
     cs.reqdata = reqdata.is_map() ? reqdata : vmap();
     CtxPtr ctx = this->utility->makeContext(cs, this->entctx);
 
-    return runOp(ctx, [this, ctx]() {
+    runOp(ctx, [this, ctx]() {
       if (ctx->result) {
         if (!is_nullish(ctx->result->resdata)) {
           Value d = Helpers::toMapAny(Struct::clone(ctx->result->resdata));
@@ -17,6 +17,12 @@
         }
       }
     });
+
+    // The operation resolves to THIS entity: runOp has just absorbed the
+    // result into it, and the caller reaches the record through data().
+    // See AGENTS.md "Entity operations return ENTITIES".
+
+    return this->self();
   }
 
 // EJECT-END

package/project/.sdk/src/cmp/cpp/fragment/EntityListOp.fragment.cpp

@@ -1,6 +1,6 @@
 // EJECT-START
 
-  Value list(const Value& reqmatch, const Value& ctrl) override {
+  std::vector<SdkEntityPtr> list(const Value& reqmatch, const Value& ctrl) override {
     CtxSpec cs;
     cs.setOpname("list");
     cs.ctrlMap = ctrl.is_map() ? ctrl : vmap();
@@ -9,13 +9,29 @@
     cs.reqmatch = reqmatch.is_map() ? reqmatch : vmap();
     CtxPtr ctx = this->utility->makeContext(cs, this->entctx);
 
-    return runOp(ctx, [this, ctx]() {
+    Value out = runOp(ctx, [this, ctx]() {
       if (ctx->result) {
         if (ctx->result->resmatch.is_map()) {
           this->match_ = ctx->result->resmatch;
         }
       }
     });
+
+    // `list` resolves to one ENTITY per record. makeResult cannot build them
+    // here - it works in Value, which has no slot for an entity - so the op
+    // does, mirroring what the dynamic targets get from makeResult.
+    std::vector<SdkEntityPtr> items;
+    if (out.is_list()) {
+      for (const auto& entry : *out.as_list()) {
+        SdkEntityPtr ent = std::static_pointer_cast<SdkEntity>(this->make());
+        if (entry.is_map()) {
+          ent->data(entry);
+        }
+        items.push_back(ent);
+      }
+    }
+
+    return items;
   }
 
 // EJECT-END

package/project/.sdk/src/cmp/cpp/fragment/EntityLoadOp.fragment.cpp

@@ -1,6 +1,6 @@
 // EJECT-START
 
-  Value load(const Value& reqmatch, const Value& ctrl) override {
+  SdkEntityPtr load(const Value& reqmatch, const Value& ctrl) override {
     CtxSpec cs;
     cs.setOpname("load");
     cs.ctrlMap = ctrl.is_map() ? ctrl : vmap();
@@ -9,7 +9,7 @@
     cs.reqmatch = reqmatch.is_map() ? reqmatch : vmap();
     CtxPtr ctx = this->utility->makeContext(cs, this->entctx);
 
-    return runOp(ctx, [this, ctx]() {
+    runOp(ctx, [this, ctx]() {
       if (ctx->result) {
         if (ctx->result->resmatch.is_map()) {
           this->match_ = ctx->result->resmatch;
@@ -20,6 +20,12 @@
         }
       }
     });
+
+    // The operation resolves to THIS entity: runOp has just absorbed the
+    // result into it, and the caller reaches the record through data().
+    // See AGENTS.md "Entity operations return ENTITIES".
+
+    return this->self();
   }
 
 // EJECT-END

package/project/.sdk/src/cmp/cpp/fragment/EntityRemoveOp.fragment.cpp

@@ -1,6 +1,6 @@
 // EJECT-START
 
-  Value remove(const Value& reqmatch, const Value& ctrl) override {
+  SdkEntityPtr remove(const Value& reqmatch, const Value& ctrl) override {
     CtxSpec cs;
     cs.setOpname("remove");
     cs.ctrlMap = ctrl.is_map() ? ctrl : vmap();
@@ -9,13 +9,22 @@
     cs.reqmatch = reqmatch.is_map() ? reqmatch : vmap();
     CtxPtr ctx = this->utility->makeContext(cs, this->entctx);
 
-    return runOp(ctx, [this, ctx]() {
+    runOp(ctx, [this, ctx]() {
       if (ctx->result) {
         if (ctx->result->resmatch.is_map()) {
           this->match_ = ctx->result->resmatch;
         }
       }
     });
+
+    // The operation resolves to THIS entity: runOp has just absorbed the
+    // result into it, and the caller reaches the record through data().
+    // See AGENTS.md "Entity operations return ENTITIES".
+
+    // A removed entity keeps its data but is no longer a live record.
+    this->markDeleted();
+
+    return this->self();
   }
 
 // EJECT-END

package/project/.sdk/src/cmp/cpp/fragment/EntityUpdateOp.fragment.cpp

@@ -1,6 +1,6 @@
 // EJECT-START
 
-  Value update(const Value& reqdata, const Value& ctrl) override {
+  SdkEntityPtr update(const Value& reqdata, const Value& ctrl) override {
     CtxSpec cs;
     cs.setOpname("update");
     cs.ctrlMap = ctrl.is_map() ? ctrl : vmap();
@@ -9,7 +9,7 @@
     cs.reqdata = reqdata.is_map() ? reqdata : vmap();
     CtxPtr ctx = this->utility->makeContext(cs, this->entctx);
 
-    return runOp(ctx, [this, ctx]() {
+    runOp(ctx, [this, ctx]() {
       if (ctx->result) {
         if (!is_nullish(ctx->result->resdata)) {
           Value d = Helpers::toMapAny(Struct::clone(ctx->result->resdata));
@@ -17,6 +17,12 @@
         }
       }
     });
+
+    // The operation resolves to THIS entity: runOp has just absorbed the
+    // result into it, and the caller reaches the record through data().
+    // See AGENTS.md "Entity operations return ENTITIES".
+
+    return this->self();
   }
 
 // EJECT-END

package/project/.sdk/src/cmp/csharp/Package_csharp.ts

@@ -7,6 +7,7 @@ import {
   collectDeps,
   pkgDescription,
   repoInfo,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -56,7 +57,7 @@ const Package = cmp(async function Package(props: any) {
     <NoWarn>$(NoWarn);CS8600;CS8601;CS8602;CS8603;CS8604;CS8618;CS8625;CS1591</NoWarn>
 
     <!-- NuGet package metadata (publication pending; see Makefile). -->
-    <Version>0.0.1</Version>
+    <Version>${packageVersion(model, target.name)}</Version>
     <PackageId>${Name}.Sdk</PackageId>
     <Authors>Voxgig</Authors>
     <Description>${pkgDescription(model, 'csharp')}</Description>

package/project/.sdk/src/cmp/csharp/TestDirect_csharp.ts

@@ -11,7 +11,7 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 import { formatCsValue } from './utility_csharp'
@@ -62,8 +62,8 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const entity: ModelEntity = props.entity
 
   const Name = model.const.Name
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
-  const ENTUPPER = nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')
+  const PROJECTNAME = envName(model)
+  const ENTUPPER = envToken(entity.name)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive

package/project/.sdk/src/cmp/csharp/TestEntity_csharp.ts

@@ -17,7 +17,7 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -54,8 +54,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
   }
 
   const Name = 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 authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -358,7 +358,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
   Content(`
         var ${datavar}Result = ${entvar}.Create(${datavar}, null);
-        ${datavar} = Helpers.ToMapAny(${datavar}Result);
+        ${datavar} = Helpers.ToMapAny(${datavar}Result is IEntity ce ? ce.Data() : ${datavar}Result);
         Assert.True(${datavar} != null, "expected create result to be a map");
 `)
   if (null != ctx.entity.id) {
@@ -500,7 +500,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
   Content(`
         var ${resdatavar}Result = ${entvar}.Update(${datavar}Up, null);
-        var ${resdatavar} = Helpers.ToMapAny(${resdatavar}Result);
+        var ${resdatavar} = Helpers.ToMapAny(${resdatavar}Result is IEntity ue ? ue.Data() : ${resdatavar}Result);
         Assert.True(${resdatavar} != null, "expected update result to be a map");
 `)
   if (hasEntIdU) {
@@ -569,7 +569,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
             ["id"] = ${srcdatavar}!["id"],
         };
         var ${datavar}Loaded = ${entvar}.Load(${matchvar}, null);
-        var ${datavar}LoadResult = Helpers.ToMapAny(${datavar}Loaded);
+        var ${datavar}LoadResult = Helpers.ToMapAny(${datavar}Loaded is IEntity le ? le.Data() : ${datavar}Loaded);
         Assert.True(${datavar}LoadResult != null, "expected load result to be a map");
         Assert.True(StructRunner.DeepEqual(${datavar}LoadResult!["id"], ${srcdatavar}["id"]),
             "expected load result id to match");

package/project/.sdk/src/cmp/csharp/fragment/EntityBase.fragment.cs

@@ -19,6 +19,22 @@ public abstract class ProjectNameEntityBase : IEntity
     protected Dictionary<string, object?> match = new();
     protected Context entctx;
 
+    // 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 bool _deleted = false;
+
+    public void MarkDeleted()
+    {
+        this._deleted = true;
+    }
+
+    public bool Deleted()
+    {
+        return this._deleted;
+    }
+
+
     protected ProjectNameEntityBase(ProjectNameSDK client,
         Dictionary<string, object?>? entopts, string name)
     {
@@ -167,7 +183,28 @@ public abstract class ProjectNameEntityBase : IEntity
 
         postDone();
 
-        return utility.Done(ctx);
+        var outv = 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".
+        var opname = ctx.Op?.Name;
+
+        if (ctx.Result != null && ctx.Result.Ok && "list" != opname)
+        {
+            if ("remove" == opname)
+            {
+                this.MarkDeleted();
+            }
+            return this;
+        }
+
+        return outv;
     }
 
     // Streaming operations. Runs `action` through the full pipeline and returns

package/project/.sdk/src/cmp/csharp/fragment/Main.fragment.cs

@@ -8,6 +8,15 @@ namespace ProjectNameSdk;
 
 public class ProjectNameSDK
 {
+    // NOTE: type references in EXPRESSION position are `global::`-qualified
+    // throughout this class. Entity accessors are PascalCase methods declared
+    // on it (see MainEntity_csharp), so an entity named `utility` declares
+    // `Utility(...)` here and C# then resolves the simple name `Utility` in an
+    // expression to the METHOD, not the type: "'X.Utility(...)' is a method,
+    // which is not valid in the given context". Qualifying makes the class
+    // immune to that whatever the API names its entities. Type POSITIONS
+    // (field and return types) are unaffected and stay unqualified.
+
     public string Mode = "live";
     private Dictionary<string, object?> _options;
     private readonly Utility _utility;
@@ -18,7 +27,7 @@ public class ProjectNameSDK
     {
         _utility = new Utility();
 
-        var config = SdkConfig.MakeConfig();
+        var config = global::ProjectNameSdk.SdkConfig.MakeConfig();
 
         _rootctx = _utility.MakeContext(new Dictionary<string, object?>
         {
@@ -31,8 +40,8 @@ public class ProjectNameSDK
 
         _options = _utility.MakeOptions(_rootctx);
 
-        if (Equals(StructUtils.GetPath(_options,
-            StructUtils.Jt("feature", "test", "active")), true))
+        if (Equals(global::Voxgig.Struct.StructUtils.GetPath(_options,
+            global::Voxgig.Struct.StructUtils.Jt("feature", "test", "active")), true))
         {
             Mode = "test";
         }
@@ -45,25 +54,25 @@ public class ProjectNameSDK
         // features (retry/cache/netsim/proxy/ratelimit) wrap whatever is
         // current, so `test` must be added before them to sit at the base of
         // the chain.
-        var featureOpts = Helpers.ToMapAny(StructUtils.GetProp(_options, "feature"))
+        var featureOpts = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(_options, "feature"))
             ?? new Dictionary<string, object?>();
-        var featureOrder = StructUtils.GetPath(_options,
-            StructUtils.Jt("__derived__", "featureorder")) as List<object?>
+        var featureOrder = global::Voxgig.Struct.StructUtils.GetPath(_options,
+            global::Voxgig.Struct.StructUtils.Jt("__derived__", "featureorder")) as List<object?>
             ?? new List<object?>();
         foreach (var fnameObj in featureOrder)
         {
             var fname = fnameObj as string ?? "";
-            var fopts = Helpers.ToMapAny(StructUtils.GetProp(featureOpts, fname));
+            var fopts = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(featureOpts, fname));
             if (fopts != null &&
                 fopts.TryGetValue("active", out var active) &&
                 active is bool ab && ab)
             {
-                _utility.FeatureAdd(_rootctx, SdkConfig.MakeFeature(fname));
+                _utility.FeatureAdd(_rootctx, global::ProjectNameSdk.SdkConfig.MakeFeature(fname));
             }
         }
 
         // Add extension features.
-        if (StructUtils.GetProp(_options, "extend") is List<object?> extList)
+        if (global::Voxgig.Struct.StructUtils.GetProp(_options, "extend") is List<object?> extList)
         {
             foreach (var f in extList)
             {
@@ -85,13 +94,13 @@ public class ProjectNameSDK
 
     public Dictionary<string, object?> OptionsMap()
     {
-        return StructUtils.Clone(_options) as Dictionary<string, object?>
+        return global::Voxgig.Struct.StructUtils.Clone(_options) as Dictionary<string, object?>
             ?? new Dictionary<string, object?>();
     }
 
     public Utility GetUtility()
     {
-        return Utility.Copy(_utility);
+        return global::ProjectNameSdk.Utility.Copy(_utility);
     }
 
     public Context GetRootCtx()
@@ -105,7 +114,7 @@ public class ProjectNameSDK
 
         fetchargs ??= new Dictionary<string, object?>();
 
-        var ctrl = Helpers.ToMapAny(StructUtils.GetProp(fetchargs, "ctrl"))
+        var ctrl = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "ctrl"))
             ?? new Dictionary<string, object?>();
 
         var ctx = utility.MakeContext(new Dictionary<string, object?>
@@ -116,23 +125,23 @@ public class ProjectNameSDK
 
         var options = _options;
 
-        var path = StructUtils.GetProp(fetchargs, "path") as string ?? "";
-        var method = StructUtils.GetProp(fetchargs, "method") as string ?? "";
+        var path = global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "path") as string ?? "";
+        var method = global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "method") as string ?? "";
         if (method == "")
         {
             method = "GET";
         }
 
-        var pathParams = Helpers.ToMapAny(StructUtils.GetProp(fetchargs, "params"))
+        var pathParams = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "params"))
             ?? new Dictionary<string, object?>();
-        var query = Helpers.ToMapAny(StructUtils.GetProp(fetchargs, "query"))
+        var query = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "query"))
             ?? new Dictionary<string, object?>();
 
         var headers = utility.PrepareHeaders(ctx);
 
-        var basev = StructUtils.GetProp(options, "base") as string ?? "";
-        var prefix = StructUtils.GetProp(options, "prefix") as string ?? "";
-        var suffix = StructUtils.GetProp(options, "suffix") as string ?? "";
+        var basev = global::Voxgig.Struct.StructUtils.GetProp(options, "base") as string ?? "";
+        var prefix = global::Voxgig.Struct.StructUtils.GetProp(options, "prefix") as string ?? "";
+        var suffix = global::Voxgig.Struct.StructUtils.GetProp(options, "suffix") as string ?? "";
 
         ctx.Spec = new Spec(new Dictionary<string, object?>
         {
@@ -144,12 +153,12 @@ public class ProjectNameSDK
             ["params"] = pathParams,
             ["query"] = query,
             ["headers"] = headers,
-            ["body"] = StructUtils.GetProp(fetchargs, "body"),
+            ["body"] = global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "body"),
             ["step"] = "start",
         });
 
         // Merge user-provided headers.
-        if (StructUtils.GetProp(fetchargs, "headers") is Dictionary<string, object?> uhm)
+        if (global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "headers") is Dictionary<string, object?> uhm)
         {
             foreach (var kv in uhm)
             {
@@ -178,13 +187,13 @@ public class ProjectNameSDK
     // Is this raw-access op permitted by the SDK's allow.op option?
     private bool OpAllowed(string op)
     {
-        return StructUtils.GetPath(_options, StructUtils.Jt("allow", "op"))
+        return global::Voxgig.Struct.StructUtils.GetPath(_options, global::Voxgig.Struct.StructUtils.Jt("allow", "op"))
             is string allow && allow.Contains(op);
     }
 
     private Dictionary<string, object?> OpDenied(string op)
     {
-        var allow = StructUtils.GetPath(_options, StructUtils.Jt("allow", "op"))
+        var allow = global::Voxgig.Struct.StructUtils.GetPath(_options, global::Voxgig.Struct.StructUtils.Jt("allow", "op"))
             as string ?? "";
         return new Dictionary<string, object?>
         {
@@ -219,7 +228,7 @@ public class ProjectNameSDK
 
         fetchargs ??= new Dictionary<string, object?>();
 
-        var ctrl = Helpers.ToMapAny(StructUtils.GetProp(fetchargs, "ctrl"))
+        var ctrl = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "ctrl"))
             ?? new Dictionary<string, object?>();
 
         var ctx = utility.MakeContext(new Dictionary<string, object?>
@@ -255,8 +264,8 @@ public class ProjectNameSDK
 
         if (fetched is Dictionary<string, object?> fm)
         {
-            var status = Helpers.ToInt(StructUtils.GetProp(fm, "status"));
-            var headers = StructUtils.GetProp(fm, "headers");
+            var status = global::ProjectNameSdk.Helpers.ToInt(global::Voxgig.Struct.StructUtils.GetProp(fm, "status"));
+            var headers = global::Voxgig.Struct.StructUtils.GetProp(fm, "headers");
 
             // No-body responses (204, 304) and explicit zero content-length
             // must skip JSON parsing - calling json() on an empty body errors.
@@ -264,12 +273,12 @@ public class ProjectNameSDK
             if (headers is Dictionary<string, object?> hm &&
                 hm.TryGetValue("content-length", out var cl) && cl != null)
             {
-                contentLength = StructUtils.Stringify(cl);
+                contentLength = global::Voxgig.Struct.StructUtils.Stringify(cl);
             }
             var noBody = status == 204 || status == 304 || contentLength == "0";
 
             object? jsonData = null;
-            if (!noBody && StructUtils.GetProp(fm, "json") is Func<object?> jf)
+            if (!noBody && global::Voxgig.Struct.StructUtils.GetProp(fm, "json") is Func<object?> jf)
             {
                 // jf() returns null on parse error in our fetcher.
                 jsonData = jf();
@@ -333,12 +342,12 @@ public class ProjectNameSDK
         // ok:false with no err — so returning early on status would discard
         // the server's own diagnostics, which are the only useful part of
         // that response.
-        var errors = StructUtils.GetPath(res, StructUtils.Jt("data", "errors"))
+        var errors = global::Voxgig.Struct.StructUtils.GetPath(res, global::Voxgig.Struct.StructUtils.Jt("data", "errors"))
             as List<object?>;
 
         if (null != errors && 0 < errors.Count)
         {
-            var msg = StructUtils.GetProp(errors[0], "message") as string;
+            var msg = global::Voxgig.Struct.StructUtils.GetProp(errors[0], "message") as string;
             if (string.IsNullOrEmpty(msg))
             {
                 msg = "graphql error";
@@ -356,14 +365,14 @@ public class ProjectNameSDK
     public static ProjectNameSDK TestSDK(Dictionary<string, object?>? testopts,
         Dictionary<string, object?>? sdkopts)
     {
-        sdkopts = StructUtils.Clone(sdkopts ?? new Dictionary<string, object?>())
+        sdkopts = global::Voxgig.Struct.StructUtils.Clone(sdkopts ?? new Dictionary<string, object?>())
             as Dictionary<string, object?> ?? new Dictionary<string, object?>();
 
-        testopts = StructUtils.Clone(testopts ?? new Dictionary<string, object?>())
+        testopts = global::Voxgig.Struct.StructUtils.Clone(testopts ?? new Dictionary<string, object?>())
             as Dictionary<string, object?> ?? new Dictionary<string, object?>();
         testopts["active"] = true;
 
-        StructUtils.SetPath(sdkopts, StructUtils.Jt("feature", "test"), testopts);
+        global::Voxgig.Struct.StructUtils.SetPath(sdkopts, global::Voxgig.Struct.StructUtils.Jt("feature", "test"), testopts);
 
         var sdk = new ProjectNameSDK(sdkopts)
         {

package/project/.sdk/src/cmp/dart/Package_dart.ts

@@ -7,6 +7,7 @@ import {
   pkgDescription,
   keywords,
   repoInfo,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -39,7 +40,7 @@ const Package = cmp(async function Package(props: any) {
     Content(`name: ${dartPackageName(model)}
 description: >-
   ${pkgDescription(model, target.name)}
-version: 0.0.1
+version: ${packageVersion(model, target.name)}
 homepage: ${repoUrl}
 repository: ${repoUrl}
 issue_tracker: ${issuesUrl}

package/project/.sdk/src/cmp/dart/ReadmeEntity_dart.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -22,6 +22,17 @@ function dartLit(type: any, placeholder: string = 'example'): string {
 
 
 // Op method spellings + descriptions (language-agnostic wording).
+// A `list()` on a NESTED entity needs its parent path params. The
+// quickstart used to emit `client.Moon().list()` for an entity at
+// `/planet/{planet_id}/moon`, which 404s against a live server from a
+// half-built URL — indistinguishable from "no such record". The model
+// already marks those params `reqd: true`; matchArg renders exactly them.
+function listMatchArg(ent: any): string {
+  const idF = entityIdField(ent)
+  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
 const OP_DESC: Record<string, { method: string, desc: string }> = {
   load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
   list:   { method: 'list()',        desc: 'List entities, optionally matching the given criteria.' },
@@ -132,7 +143,7 @@ final ${eVar} = await client.${entity.Name}().load(${loadArg});
       Content(`#### Example: List
 
 \`\`\`dart
-final ${eVar}s = await client.${entity.Name}().list();
+final ${eVar}s = await client.${entity.Name}().list(${listMatchArg(entity)});
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/dart/ReadmeHowto_dart.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 throw on error.
+    ? `// Entity ops return the ENTITY and throws on error;
+// call data() for the record.
 final ${eVar} = await client.${eName}().${primaryOp}(${testArg});
 // ${eVar} contains the mock response record
 print(${eVar});`