@voxgig/sdkgen 2.0.2 → 3.0.0

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

@@ -12,8 +12,11 @@ const Gitignore = cmp(async function Gitignore(_props: any) {
 node_modules/
 
 # Build output
-dist/
-dist-test/
+#
+# dist/ and dist-test/ are COMMITTED, not ignored: the compiled SDK and the
+# compiled test suite are part of the published repo, so a consumer can read
+# and run them straight from a clone without a build step. Only the
+# incremental-build bookkeeping is ignored.
 *.tsbuildinfo
 
 # Coverage

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

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
-  entityClassName, entityCollection,
+  entityClassName, entityCollection, srcFeatureExcludes,
 } from '@voxgig/sdkgen'
 
 
@@ -43,6 +43,9 @@ const Main = cmp(async function Main(props: any) {
 
   Copy({
     from: 'tm/' + target.name,
+    // Root copies src/feature/<name>/ per ACTIVE feature; keep this blanket
+    // copy from restoring one that was switched off after `target add`.
+    exclude: srcFeatureExcludes(model),
     replace: {
       ...props.ctx$.stdrep,
     }

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

@@ -11,6 +11,7 @@ import {
   repoInfo,
   PUBLISHER,
   PUBLISHER_URL,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -54,7 +55,7 @@ const Package = cmp(async function Package(props: any) {
 
   const pkg = {
     name: packageName(model, 'npm'),
-    version: `0.0.1`,
+    version: packageVersion(model, target.name),
     description: pkgDescription(model, target.name),
     keywords: keywords(model),
     homepage: `${repoUrl}#readme`,
@@ -63,6 +64,14 @@ const Package = cmp(async function Package(props: any) {
     main: `dist/${SdkName}SDK.js`,
     type: 'commonjs',
     types: `dist/${SdkName}SDK.d.ts`,
+
+    // What actually ships. Without `files`, `npm publish` packs everything
+    // not gitignored — the test suite, dist-test/, the Makefile, the agent
+    // guides — into the published tarball. `src` IS included: the emitted
+    // .js.map files point back at it, so shipping it is what makes stack
+    // traces in a consumer resolve to SDK source. README/LICENSE/package.json
+    // are always included by npm and need no entry.
+    files: ['dist', 'src'],
     scripts: {
       // `test` and `test-coverage` run the COMPILED suite in dist-test/, which
       // a fresh clone does not have — the glob then matches nothing and the

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -12,6 +12,17 @@ import { exampleValue } from './utility_ts'
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
 // methods with optional ctrl. The op descriptions are language-agnostic.
+// 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(match)',   desc: 'List entities matching the criteria.' },
@@ -124,7 +135,7 @@ const ${eVar} = await client.${entity.Name}().load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`ts
-const ${eVar}s = await client.${entity.Name}().list()
+const ${eVar}s = await client.${entity.Name}().list(${listMatchArg(entity)})
 \`\`\`
 
 `)

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

@@ -67,7 +67,8 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // A direct()-only SDK (no ops anywhere) shows a direct() test call instead.
   const testModeExample = primaryOp
     ? `const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
-// ${eVar} is a bare entity populated with mock response data
+// ${eVar} is the entity, populated with mock response data
+// — call ${eVar}.data() for the record itself
 console.log(${eVar})`
     : `const result = await client.direct({ path: '/api/resource', method: 'GET' })
 console.log(result)`

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,6 +10,17 @@ import {
 import { exampleValue } from './utility_ts'
 
 
+// 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 ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -63,10 +74,12 @@ const client = ${ctor}
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` resolves to an array of ${eName} objects — iterate it directly:
+\`list()\` resolves to an array of ${eName} ENTITIES — every operation
+resolves to entities, not raw records. Iterate them directly, and call
+\`.data()\` on one for the record it holds:
 
 \`\`\`ts
-const ${eVar}s = await client.${eName}().list()
+const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
 
 for (const ${eVar} of ${eVar}s) {
   console.log(${eVar})
@@ -195,8 +208,10 @@ try {
         const matchType = matchItem ? matchItem.type : null
         return null == matchType || null == dataIdType || matchType === dataIdType
       }
+      // `create` resolves to the ENTITY, so the id is reached through
+      // `.data()` — `created.id` is a TS2339 on the entity class.
       const idValueFor = (opname: string): string => usesCreatedId(opname)
-        ? `created.${dataIdF}!`
+        ? `created.data().${dataIdF}!`
         : exampleValue(exampleEntity, exampleEntity.op[opname], idF as string, 'example_id')
 
       Content(`### 4. Create, update, and remove
@@ -206,7 +221,7 @@ try {
       if (opnames.includes('create')) {
         const createLines = exampleFields('create')
         const createBody = createLines.length ? '\n' + createLines.join('\n') + '\n' : ''
-        Content(`// Create — returns the created ${eName}
+        Content(`// Create — returns the created ${eName} ENTITY (.data() for the record)
 const created = await client.${eName}().create({${createBody}})
 
 `)
@@ -216,7 +231,7 @@ const created = await client.${eName}().create({${createBody}})
         // type carries one, else a literal), plus a couple of patch fields.
         const updateLines = (idF ? [`  ${idF}: ${idValueFor('update')},`] : []).concat(exampleFields('update'))
         const updateBody = updateLines.length ? '\n' + updateLines.join('\n') + '\n' : ''
-        Content(`// Update${usesCreatedId('update') ? ' — the id comes straight off the returned entity' : ''}
+        Content(`// Update${usesCreatedId('update') ? ' — the id comes off the returned entity\'s data()' : ''}
 const updated = await client.${eName}().update({${updateBody}})
 
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, entityActions, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -9,6 +9,17 @@ import {
 import { exampleValue } from './utility_ts'
 
 
+// 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_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(match: object, ctrl?: object)',
@@ -254,6 +265,45 @@ const ${eVar} = client.${ent.Name}()
       }
 
 
+      // Custom actions.
+      //
+      // A POST route like `/api/planet/{id}/terraform` is folded into the
+      // `create` op as an alternative point, selected at call time by
+      // `$action`. The mechanism was implemented and documented NOWHERE — so
+      // for an API with two such routes, two of its six endpoints were
+      // unreachable by anyone reading the docs. A user who wanted `terraform`
+      // had to fall back to `direct()` and rebuild the URL by hand, which is
+      // exactly what the entity model exists to spare them.
+      const actions = entityActions(ent)
+      if (0 < actions.length) {
+        Content(`### Actions
+
+This entity exposes custom API actions in addition to the standard
+operations. Select one with \`$action\` in the call's argument; the
+remaining keys are sent as that action's payload.
+
+| Action | Route | Call |
+| --- | --- | --- |
+`)
+        actions.forEach((a: any) => {
+          Content(`| \`${a.action}\` | \`${a.path}\` | \`client.${ent.Name}().${a.op}({ $action: '${a.action}', ... })\` |
+`)
+        })
+
+        Content(`
+An action returns that action's OWN response, which is not necessarily a
+${ent.Name} record — check the API definition for its shape.
+
+\`\`\`ts
+const result = await client.${ent.Name}().${actions[0].op}({
+  $action: '${actions[0].action}',
+  /* ...the action's own arguments */
+})
+\`\`\`
+
+`)
+      }
+
       // Operation details
       if (opnames.length > 0) {
         Content(`### Operations
@@ -292,7 +342,7 @@ const result = await client.${ent.Name}().${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`ts
-const results = await client.${ent.Name}().${opname}()
+const results = await client.${ent.Name}().${opname}(${listMatchArg(ent)})
 \`\`\`
 
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,6 +10,17 @@ import {
 import { exampleValue } from './utility_ts'
 
 
+// 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 ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -36,8 +47,8 @@ const client = ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns ${eName}[])
-const ${eVar}s = await client.${eName}().list()
+      Content(`// List all ${eName.toLowerCase()}s (returns ${eName}Entity[] — .data() for the record)
+const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
 for (const ${eVar} of ${eVar}s) {
   console.log(${eVar})
 }

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

@@ -18,8 +18,39 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   // `load` on an op-less entity like Cloudsmith's `Abort`.
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
 
+  // The mock SEEDS NOTHING on its own.
+  //
+  // `SDK.test()` with no argument used to be shown alongside "populated with
+  // mock data" — and returned an empty array. The seed shape
+  // (`{ entity: { <name>: { <id>: {...} } } }`) was documented nowhere; the
+  // only way to find it was to read TestFeature.ts. Offline test mode is a
+  // headline feature of these SDKs, so its one worked example has to run.
+  const seedEntity = exampleEntity ? nom(exampleEntity, 'name') : ''
+  const seedFields = exampleEntity ?
+    opRequestShape(exampleEntity, 'create').items
+      .filter((it: any) => !it.optional)
+      .slice(0, 3) : []
+
+  const seedId = 'test01'
+  const seedBody = [
+    `${jsKey('id')}: '${seedId}'`,
+    ...seedFields
+      .filter((it: any) => 'id' !== it.name)
+      .map((it: any) => `${jsKey(it.name)}: ${exampleValue(
+        exampleEntity, exampleEntity.op && exampleEntity.op.create, it.name,
+        'example_' + it.name)}`),
+  ].join(', ')
+
   Content(`\`\`\`ts
-const client = ${model.const.Name}SDK.test()
+// The offline mock starts EMPTY — seed it with the records the test needs.
+// Shape: { entity: { <entity-name>: { <id>: <record> } } }
+const client = ${model.const.Name}SDK.test({
+  entity: {
+    ${seedEntity}: {
+      ${seedId}: { ${seedBody} },
+    },
+  },
+})
 `)
 
   if (exampleEntity && primaryOp) {
@@ -51,7 +82,8 @@ const client = ${model.const.Name}SDK.test()
         `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
     }
     Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
-// ${eVar} is ${'list' === primaryOp ? `an array of bare ${eName} records` : `a bare ${eName}`} populated with mock data
+// ${eVar} is ${'list' === primaryOp ? `an array of ${eName} entities` : `the ${eName} entity`}, populated with mock data
+// — call ${eVar}${'list' === primaryOp ? '[0]' : ''}.data() for the record itself
 console.log(${eVar})
 `)
   }

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

@@ -18,7 +18,7 @@ import {
   snakify,
   isAuthActive,
   jsProp,
-  jsOptProp,
+  jsOptProp, envName, envToken, liveStrict
 } from '@voxgig/sdkgen'
 
 
@@ -37,8 +37,11 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const ff = projectPath('src/cmp/ts/fragment/')
 
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
-  const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
+  // Does a live run ASSERT, or merely observe? See helpers/testPolicy.
+  const strict = liveStrict(model, target.name)
+
+  const PROJECTNAME = envName(model)
+  const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -136,11 +139,11 @@ function unwrapListData(data: any): any[] | null {
         Slot({ name: 'direct' }, () => {
 
           if (hasLoad) {
-            generateDirectLoad(model, entity)
+            generateDirectLoad(model, entity, strict)
           }
 
           if (hasList) {
-            generateDirectList(model, entity)
+            generateDirectList(model, entity, strict)
           }
         })
 
@@ -150,7 +153,7 @@ function unwrapListData(data: any): any[] | null {
 })
 
 
-function generateDirectLoad(model: Model, entity: ModelEntity) {
+function generateDirectLoad(model: Model, entity: ModelEntity, strict: boolean) {
   const loadOp = entity.op?.load
   const loadPoint: ModelPoint | undefined = loadOp?.points?.[0]
 
@@ -318,6 +321,31 @@ ${loadParams.map((p: any, i: number) => `      ${jsProp('params', p.name)} = 'di
     ? `    if (skipIfMissingIds(t, setup, ${JSON.stringify(liveIdKeys)})) return\n`
     : ''
 
+  // Live-mode leniency is a MODEL decision (main.kit.test.live.strict).
+  // The default stays lenient: a fleet SDK generated against an arbitrary
+  // public API 4xxes on synthetic IDs, and asserting would mean permanent
+  // red. A project that owns its test server wants the opposite — without
+  // it, the suite passes with nothing listening on the port.
+  const offlineChecks = `      assert(result.ok === true)
+      assert(result.status === 200)
+      assert(null != result.data)
+      assert(result.data.id === 'direct01')
+      assert(calls.length === 1)
+      assert(calls[0].init.method === 'GET')
+${paramAsserts}`
+
+  const loadChecks = strict ?
+    offlineChecks.replace(/^ {6}/gm, '    ').replace(/^ {4}$/gm, '') :
+    `    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.
+      if (!result.ok || result.status < 200 || result.status >= 300) {
+        return
+      }
+    } else {
+${offlineChecks}    }`
+
   Content(`
   test('direct-load-${entity.name}', async (t: any) => {
     const setup = directSetup({ id: 'direct01' })
@@ -335,27 +363,13 @@ ${liveParamsBlock}
       query,
     })
 
-    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.
-      if (!result.ok || result.status < 200 || result.status >= 300) {
-        return
-      }
-    } else {
-      assert(result.ok === true)
-      assert(result.status === 200)
-      assert(null != result.data)
-      assert(result.data.id === 'direct01')
-      assert(calls.length === 1)
-      assert(calls[0].init.method === 'GET')
-${paramAsserts}    }
+${loadChecks}
   })
 `)
 }
 
 
-function generateDirectList(model: Model, entity: ModelEntity) {
+function generateDirectList(model: Model, entity: ModelEntity, strict: boolean) {
   const listOp = entity.op?.list
   const listPoint: ModelPoint | undefined = listOp?.points?.[0]
 
@@ -418,6 +432,33 @@ ${mockLines}
     ? `    if (skipIfMissingIds(t, setup, ${JSON.stringify(liveIdKeys)})) return\n`
     : ''
 
+  // See generateDirectLoad: leniency is main.kit.test.live.strict.
+  const offlineChecks = `      assert(result.ok === true)
+      assert(result.status === 200)
+      assert(null != result.data)
+      const listArr = unwrapListData(result.data)
+      assert(Array.isArray(listArr))
+      assert(listArr!.length === 2)
+      assert(calls.length === 1)
+      assert(calls[0].init.method === 'GET')
+${paramAsserts}`
+
+  const listChecks = strict ?
+    offlineChecks.replace(/^ {6}/gm, '    ').replace(/^ {4}$/gm, '') :
+    `    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.
+      if (!result.ok || result.status < 200 || result.status >= 300) {
+        return
+      }
+      const listArr = unwrapListData(result.data)
+      if (!Array.isArray(listArr)) {
+        return
+      }
+    } else {
+${offlineChecks}    }`
+
   Content(`
   test('direct-list-${entity.name}', async (t: any) => {
     const setup = directSetup([{ id: 'direct01' }, { id: 'direct02' }])
@@ -432,27 +473,7 @@ ${paramsBlock}
       query,
     })
 
-    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.
-      if (!result.ok || result.status < 200 || result.status >= 300) {
-        return
-      }
-      const listArr = unwrapListData(result.data)
-      if (!Array.isArray(listArr)) {
-        return
-      }
-    } else {
-      assert(result.ok === true)
-      assert(result.status === 200)
-      assert(null != result.data)
-      const listArr = unwrapListData(result.data)
-      assert(Array.isArray(listArr))
-      assert(listArr!.length === 2)
-      assert(calls.length === 1)
-      assert(calls[0].init.method === 'GET')
-${paramAsserts}    }
+${listChecks}
   })
 `)
 }

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

@@ -30,7 +30,7 @@ import {
   cmp,
   each,
   isAuthActive,
-  entityDataIdField,
+  entityDataIdField, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -61,8 +61,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const target = props.target
   const entity: ModelEntity = props.entity
 
-  const PROJENVNAME = nom(model.const, 'NAME').replace(/[^A-Z_]/g, '_')
-  const ENTENVNAME = nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')
+  const PROJENVNAME = envName(model)
+  const ENTENVNAME = envToken(entity.name)
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
     ? `\n    '${PROJENVNAME}_APIKEY': 'NONE',`
@@ -300,7 +300,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
   const hasEntIdC = null != entity.id
 
   Content(`
-    ${datavar} = await ${entvar}.create(${datavar})
+    ${datavar} = (await ${entvar}.create(${datavar})).data()
 `)
   if (hasEntIdC) {
     Content(`    assert(null != ${datavar}.id)
@@ -341,7 +341,7 @@ const generateList: OpGen = (ctx, step, index) => {
   })
 
   Content(`
-    const ${listvar} = await ${entvar}.list(${matchvar})
+    const ${listvar} = (await ${entvar}.list(${matchvar})).map((e: any) => e.data())
 `)
   const allSteps = flow.step
   for (let vI = 0; vI < step.valid.length; vI++) {
@@ -420,7 +420,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-    const ${resdatavar} = await ${entvar}.update(${datavar})
+    const ${resdatavar} = (await ${entvar}.update(${datavar})).data()
 `)
   if (hasEntIdU) {
     Content(`    assert(${resdatavar}.id === ${datavar}.id)
@@ -508,13 +508,13 @@ const generateLoad: OpGen = (ctx, step, index) => {
   if (hasEntId) {
     Content(`    const ${matchvar}: any = {}
     ${matchvar}.id = ${srcdatavar}.id
-    const ${datavar} = await ${entvar}.load(${matchvar})
+    const ${datavar} = (await ${entvar}.load(${matchvar})).data()
     assert(${datavar}.id === ${srcdatavar}.id)
 `)
   }
   else {
     Content(`    const ${matchvar}: any = {}
-    const ${datavar} = await ${entvar}.load(${matchvar})
+    const ${datavar} = (await ${entvar}.load(${matchvar})).data()
     assert(null != ${datavar})
 `)
   }

package/project/.sdk/src/cmp/ts/fragment/Direct.test.fragment.ts

@@ -19,8 +19,8 @@ import {
 describe('EntityNameDirect', async () => {
 
   // Per-test live pacing. Delay is read from sdk-test-control.json's
-  // `test.live.delayMs`; only sleeps when PROJECTNAME_TEST_LIVE=TRUE.
-  afterEach(liveDelay('PROJECTNAME_TEST_LIVE'))
+  // `test.live.delayMs`; only sleeps when PROJECTENV_TEST_LIVE=TRUE.
+  afterEach(liveDelay('PROJECTENV_TEST_LIVE'))
 
   test('direct-exists', async () => {
     const sdk = new ProjectNameSDK({

package/project/.sdk/src/cmp/ts/fragment/Entity.test.fragment.ts

@@ -26,8 +26,8 @@ import {
 describe('EntityNameEntity', async () => {
 
   // Per-test live pacing. Delay is read from sdk-test-control.json's
-  // `test.live.delayMs`; only sleeps when PROJECTNAME_TEST_LIVE=TRUE.
-  afterEach(liveDelay('PROJECTNAME_TEST_LIVE'))
+  // `test.live.delayMs`; only sleeps when PROJECTENV_TEST_LIVE=TRUE.
+  afterEach(liveDelay('PROJECTENV_TEST_LIVE'))
 
   test('instance', async () => {
     const testsdk = ProjectNameSDK.test()

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

@@ -32,6 +32,11 @@ class ProjectNameEntityBase<D = any> {
   _match: Partial<D>
   _entctx: Context
 
+  // Set once a successful `remove` resolves on this instance. The entity
+  // KEEPS the data it held — a caller can still read what was deleted — but
+  // it is no longer a live record.
+  _deleted: boolean
+
 
   constructor(client: ProjectNameSDK, entopts: any) {
     entopts = entopts || {}
@@ -42,6 +47,7 @@ class ProjectNameEntityBase<D = any> {
     this._utility = client.utility()
     this._data = {}
     this._match = {}
+    this._deleted = false
 
     const makeContext = this._utility.makeContext
 
@@ -54,6 +60,19 @@ class ProjectNameEntityBase<D = any> {
     featureHook(this._entctx, 'PostConstructEntity')
   }
 
+  // True once `remove` has succeeded on this instance. `remove` resolves to
+  // the entity like every other operation, so this is how a caller tells a
+  // removed record from a live one.
+  markDeleted(this: any): void {
+    this._deleted = true
+  }
+
+
+  deleted(this: any): boolean {
+    return true === this._deleted
+  }
+
+
   entopts() {
     return this._utility.struct.merge([{}, this._entopts])
   }
@@ -178,7 +197,12 @@ class ProjectNameEntityBase<D = any> {
 
   toJSON() {
     const struct = this._utility.struct
-    return struct.merge([{}, struct.getdef(this._data, {}), { entity$: this.Name }])
+  // The marker is NAMESPACED. It used to be `entity$` — a short, generic
+  // name, and the `$`-suffix convention is not unique to sdkgen. Seneca uses
+  // `entity$` on its own entities to hold the canon, so an SDK record fed
+  // into `entize` silently overwrote it and produced entities claiming a
+  // canon that does not exist: no error, just wrong entities.
+    return struct.merge([{}, struct.getdef(this._data, {}), { 'voxgig$entity': this.Name }])
   }