@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/js/Entity_js.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, camelify, names,
   File, Content, Folder, Fragment, Line, FeatureHook, Slot,
-  entityClassName,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 import {
@@ -22,7 +22,7 @@ const Entity = cmp(function Entity(props: any) {
   // Collision-free entity CLASS name (see entityClassName): normally
   // `<Name>Entity`, disambiguated when it would clash with another entity's
   // data-type name. The class file name and the Main require path both use this.
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
   const entrep = {
@@ -37,7 +37,7 @@ const Entity = cmp(function Entity(props: any) {
 
     File({ name: cls + '.' + target.name }, () => {
 
-      const opnames = Object.keys(entity.op)
+      const opnames = Object.keys(entity.op || {})
 
       const opfrags =
         (['load', 'list', 'create', 'update', 'remove']

package/project/.sdk/src/cmp/js/MainEntity_js.ts

@@ -1,6 +1,6 @@
 
 
-import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,13 +14,15 @@ const MainEntity = cmp(async function MainEntity(props: any) {
 
   // Return the collision-free class (entityClassName); the accessor METHOD name
   // (entity.Name) is unchanged so callers still write client.<Name>().
-  const cls = entityClassName(entity, getModelPath(model, `main.${KIT}.entity`))
+  const cls = entityClassName(entity, entityCollection(model))
 
   Content(`
   // Entity access: \`client.${entity.Name}().list()\` / \`client.${entity.Name}().load({ id })\`.
-  ${entity.Name}(data) {
+  // The argument is the entity OPTIONS object (passed to the entity
+  // constructor as entopts), not initial entity data.
+  ${entity.Name}(entopts) {
     const self = this
-    return new ${cls}(self,data)
+    return new ${cls}(self, entopts)
   }
 
 `)

package/project/.sdk/src/cmp/js/Main_js.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,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 
@@ -57,7 +57,7 @@ const Main = cmp(async function Main(props: any) {
       Line(`// ${model.const.Name} ${target.Name} SDK\n`)
 
       List({ item: entity }, ({ item }: any) => {
-        const cls = entityClassName(item, entity)
+        const cls = entityClassName(item, entityCollection(model))
         return Line(`const { ${cls} } = require('./entity/${cls}')`)
       })
 

package/project/.sdk/src/cmp/js/ReadmeEntity_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -46,7 +46,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
     // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
-    const eVar = safeVarName(entity.name, 'js')
+    const eVar = exampleVarName(entity.name, 'js')
 
     Content(`
 ### ${entity.Name}
@@ -108,7 +108,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       const loadArg = 0 < loadItems.length
         ? `{ ${loadItems.map((it: any) =>
-          `${it.name}: ${exampleValue(entity, entity.op && entity.op.load, it.name,
+          `${jsKey(it.name)}: ${exampleValue(entity, entity.op && entity.op.load, it.name,
             it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
         : ''
       Content(`#### Example: Load
@@ -144,7 +144,7 @@ const ${eVar}s = await client.${entity.Name}().list()
 const ${eVar} = await client.${entity.Name}().create({
 `)
       createItems.map((it: any) => {
-        Content(`  ${it.name}: ${exampleValue(entity, entity.op && entity.op.create, it.name, 'example_' + it.name)},
+        Content(`  ${jsKey(it.name)}: ${exampleValue(entity, entity.op && entity.op.create, it.name, 'example_' + it.name)},
 `)
       })
       Content(`})

package/project/.sdk/src/cmp/js/ReadmeHowto_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -19,7 +19,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // only when NO entity exposes any op (a direct()-only SDK).
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
-  const eVar = safeVarName(eName.toLowerCase(), 'js')
+  const eVar = exampleVarName(eName.toLowerCase(), 'js')
 
   const primaryOpDef = exampleEntity && primaryOp && exampleEntity.op && exampleEntity.op[primaryOp]
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
@@ -32,14 +32,23 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     if (!exampleEntity || !primaryOp) return ''
     if ('list' === primaryOp) return ''
     if (isMatchOp) {
-      return idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, idF, idPlaceholder)} }` : ''
+      // Every REQUIRED match key (id first), not just idF — a composite-match
+      // entity (database_id + id) needs them all. Mirrors ReadmeTopTest.
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      if (0 === items.length) return ''
+      const pairs = items.map((it: any) =>
+        `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
+          it.name === idF ? idPlaceholder : 'example_' + it.name)}`)
+      return `{ ${pairs.join(', ')} }`
     }
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)
     const chosen = required.length ? required : items.slice(0, 3)
     const pairs = chosen.map((it: any) =>
-      `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`)
+      `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`)
     return `{ ${pairs.join(', ')} }`
   }
   const testCallArg = primaryArg('test01')

package/project/.sdk/src/cmp/js/ReadmeQuick_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityOps, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityOps, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -47,7 +47,7 @@ const client = ${ctor}
     // then load/remove match on no argument and update omits the id.
     const idF = entityIdField(exampleEntity)
     // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
-    const eVar = safeVarName(exampleEntity.name, 'js')
+    const eVar = exampleVarName(exampleEntity.name, 'js')
     const exampleFields = (opname: string): string[] => {
       // ids are rendered separately as the match key for update/remove; a
       // REQUIRED id stays for create (dropping it makes the payload
@@ -64,7 +64,7 @@ const client = ${ctor}
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))
       return chosen.map((it: any) =>
-        `  ${it.name}: ${exampleValue(exampleEntity, exampleEntity.op[opname], it.name, 'example_' + it.name)},`)
+        `  ${jsKey(it.name)}: ${exampleValue(exampleEntity, exampleEntity.op[opname], it.name, 'example_' + it.name)},`)
     }
 
     // The full REQUIRED match for load/remove (id first, then parent path
@@ -77,7 +77,7 @@ const client = ${ctor}
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       return 0 < matchItems.length
         ? `{ ${matchItems.map((it: any) =>
-          `${it.name}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op[opname], it.name,
+          `${jsKey(it.name)}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op[opname], it.name,
             it.name === idF ? exampleEntity.name + '_id' : 'example_' + it.name)}`).join(', ')} }`
         : ''
     }

package/project/.sdk/src/cmp/js/ReadmeRef_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -185,7 +185,7 @@ Alias for \`${model.Name}SDK.test()\`.
       // which case load/remove match on no argument and update omits the id.
       const idF = entityIdField(ent)
       // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
-      const eVar = safeVarName(ent.name, 'js')
+      const eVar = exampleVarName(ent.name, 'js')
 
       Content(`
 ---
@@ -281,7 +281,7 @@ ${info.desc}
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
             const arg = 0 < matchItems.length
               ? `{ ${matchItems.map((it: any) =>
-                `${it.name}: ${exampleValue(ent, ent.op && ent.op[opname], it.name,
+                `${jsKey(it.name)}: ${exampleValue(ent, ent.op && ent.op[opname], it.name,
                   it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')} }`
               : ''
             Content(`\`\`\`ts
@@ -309,7 +309,7 @@ const results = await client.${ent.Name}().${opname}()
 const result = await client.${ent.Name}().create({
 `)
             createItems.map((it: any) => {
-              Content(`  ${it.name}: ${exampleValue(ent, ent.op && ent.op.create, it.name, 'example_' + it.name)},
+              Content(`  ${jsKey(it.name)}: ${exampleValue(ent, ent.op && ent.op.create, it.name, 'example_' + it.name)},
 `)
             })
             Content(`})
@@ -325,7 +325,7 @@ const result = await client.${ent.Name}().create({
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
             const updateLines = updateItems.map((it: any) =>
-              `  ${it.name}: ${exampleValue(ent, ent.op && ent.op.update, it.name,
+              `  ${jsKey(it.name)}: ${exampleValue(ent, ent.op && ent.op.update, it.name,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().update({

package/project/.sdk/src/cmp/js/ReadmeTopQuick_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -29,7 +29,7 @@ const client = ${ctor}
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const eVar = safeVarName(eName.toLowerCase(), 'js')
+    const eVar = exampleVarName(eName.toLowerCase(), 'js')
     // ACTIVE ops only — an inactive op generates no method, so an example
     // calling it would be wrong.
     const opnames = entityOps(exampleEntity)
@@ -57,7 +57,7 @@ for (const ${eVar} of ${eVar}s) {
 
     if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
-      const neVar = safeVarName(neName.toLowerCase(), 'js')
+      const neVar = exampleVarName(neName.toLowerCase(), 'js')
       const loadOp = nestedEntity.op && nestedEntity.op.load
 
       // Every REQUIRED load-match key (parent keys like page_id first, the
@@ -69,7 +69,7 @@ for (const ${eVar} of ${eVar}s) {
         .sort((a: any, b: any) =>
           (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
         .map((it: any) =>
-          `  ${it.name}: ${exampleValue(nestedEntity, loadOp, it.name,
+          `  ${jsKey(it.name)}: ${exampleValue(nestedEntity, loadOp, it.name,
             it.name === neIdF ? 'example_id' : 'example_' + it.name)},`)
 
       Content(`

package/project/.sdk/src/cmp/js/ReadmeTopTest_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -25,7 +25,7 @@ const client = ${model.const.Name}SDK.test()
   if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
     // A list() result is an array — name the variable accordingly.
-    const eVar = safeVarName(eName.toLowerCase(), 'js') +
+    const eVar = exampleVarName(eName.toLowerCase(), 'js') +
       ('list' === primaryOp ? 's' : '')
     const primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
     const idF = entityIdField(exampleEntity)
@@ -39,7 +39,7 @@ const client = ${model.const.Name}SDK.test()
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = 0 < items.length
         ? `{ ${items.map((it: any) =>
-          `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
+          `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
             it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
         : ''
     } else if ('create' === primaryOp || 'update' === primaryOp) {
@@ -48,7 +48,7 @@ const client = ${model.const.Name}SDK.test()
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
       arg = `{ ${chosen.map((it: any) =>
-        `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
+        `${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 entities' : 'a bare entity'} populated with mock data

package/project/.sdk/src/cmp/js/TestDirect_js.ts

@@ -17,6 +17,7 @@ import {
   cmp,
   snakify,
   isAuthActive,
+  jsProp,
 } from '@voxgig/sdkgen'
 
 
@@ -47,7 +48,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
       apikey: env.${PROJECTNAME}_APIKEY,`
     : ''
 
-  const opnames = Object.keys(entity.op)
+  const opnames = Object.keys(entity.op || {})
   const hasLoad = opnames.includes('load')
   const hasList = opnames.includes('list')
 
@@ -133,7 +134,7 @@ function directSetup(mockres) {
 
 
 function generateDirectLoad(model: Model, entity: ModelEntity) {
-  const loadOp = entity.op.load
+  const loadOp = entity.op?.load
   const loadPoint: ModelPoint | undefined = loadOp?.points?.[0]
 
   if (null == loadPoint) {
@@ -144,7 +145,7 @@ function generateDirectLoad(model: Model, entity: ModelEntity) {
   const loadPath = normalizePathParams(loadPoint.parts || [], loadParams, loadPoint.rename?.param)
 
   // Get list info for live mode bootstrapping
-  const listOp = entity.op.list
+  const listOp = entity.op?.list
   const listPoint = listOp?.points?.[0]
   const listParams = listPoint?.args?.params || []
   const listPath = listPoint ? normalizePathParams(listPoint.parts || [], listParams, listPoint.rename?.param) : ''
@@ -175,7 +176,7 @@ function generateDirectLoad(model: Model, entity: ModelEntity) {
     const listParamLines = liveListParams.map((lp: any) =>
       `        ${lp.name}: setup.idmap['${lp.key}'],`).join('\n')
     const ancestorParamLines = liveAncestorParams.map((lp: any) =>
-      `      params.${lp.name} = setup.idmap['${lp.key}']`).join('\n')
+      `      ${jsProp('params', lp.name)} = setup.idmap['${lp.key}']`).join('\n')
 
     liveParamsBlock = `    if (setup.live) {
       const listResult = await client.direct({
@@ -193,11 +194,11 @@ ${listParamLines}
       params.id = listData[0].id
 ${ancestorParamLines}
     } else {
-${loadParams.map((p: any, i: number) => `      params.${p.name} = 'direct0${i + 1}'`).join('\n')}
+${loadParams.map((p: any, i: number) => `      ${jsProp('params', p.name)} = 'direct0${i + 1}'`).join('\n')}
     }`
   } else {
     liveParamsBlock = `    if (!setup.live) {
-${loadParams.map((p: any, i: number) => `      params.${p.name} = 'direct0${i + 1}'`).join('\n')}
+${loadParams.map((p: any, i: number) => `      ${jsProp('params', p.name)} = 'direct0${i + 1}'`).join('\n')}
     }`
   }
 
@@ -230,7 +231,7 @@ ${paramAsserts}    }
 
 
 function generateDirectList(model: Model, entity: ModelEntity) {
-  const listOp = entity.op.list
+  const listOp = entity.op?.list
   const listPoint: ModelPoint | undefined = listOp?.points?.[0]
 
   if (null == listPoint) {
@@ -254,9 +255,9 @@ function generateDirectList(model: Model, entity: ModelEntity) {
   let paramsBlock = ''
   if (listParams.length > 0) {
     const liveLines = liveParams.map((lp: any) =>
-      `      params.${lp.name} = setup.idmap['${lp.key}']`).join('\n')
+      `      ${jsProp('params', lp.name)} = setup.idmap['${lp.key}']`).join('\n')
     const mockLines = listParams.map((p: any, i: number) =>
-      `      params.${p.name} = 'direct0${i + 1}'`).join('\n')
+      `      ${jsProp('params', p.name)} = 'direct0${i + 1}'`).join('\n')
 
     paramsBlock = `    const params = {}
     if (setup.live) {

package/project/.sdk/src/cmp/js/TestEntity_js.ts

@@ -30,6 +30,7 @@ import {
   cmp,
   each,
   isAuthActive,
+  entityDataIdField,
 } from '@voxgig/sdkgen'
 
 
@@ -270,6 +271,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
 const generateList: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
+  const hasDataId = null != entityDataIdField(entity)
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
@@ -304,12 +306,12 @@ const generateList: OpGen = (ctx, step, index) => {
     const hasRefData = validRef && allSteps.some(s => 'create' === s.op &&
       ((s.input.ref ?? entity.name + '_ref01') === validRef))
 
-    if ('ItemExists' === validator.apply && hasRefData) {
+    if ('ItemExists' === validator.apply && hasRefData && hasDataId) {
       Content(`
     assert(!isempty(select(${listvar}, { id: ${validRef}_data.id })))
 `)
     }
-    else if ('ItemNotExists' === validator.apply && hasRefData) {
+    else if ('ItemNotExists' === validator.apply && hasRefData && hasDataId) {
       Content(`
     assert(isempty(select(${listvar}, { id: ${validRef}_data.id })))
 `)
@@ -448,6 +450,9 @@ const generateLoad: OpGen = (ctx, step, index) => {
 
 const generateRemove: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
+  if (null == entityDataIdField(entity)) {
+    return
+  }
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))

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

@@ -30,37 +30,6 @@ describe('EntityNameEntity', async () => {
   })
 
 
-  // Feature #4: the entity `stream(action, ...)` method runs the op pipeline
-  // and returns an async iterator over result items. With the streaming
-  // feature active it yields the feature's incremental output; otherwise it
-  // falls back to the materialised list so `stream` always yields.
-  test('stream', async () => {
-    const seed = {
-      entity: {
-        EntityLower: { s1: { id: 's1' }, s2: { id: 's2' }, s3: { id: 's3' } }
-      }
-    }
-
-    // Fallback: streaming inactive -> yields the materialised list items.
-    const base = ProjectNameSDK.test(seed)
-    const seen = []
-    for await (const item of base.EntityName().stream('list')) {
-      seen.push(item)
-    }
-    assert.equal(seen.length, 3)
-
-    // Inbound: streaming active -> yields each item from the feature iterator.
-    if (config.feature && config.feature.streaming) {
-      const sdk = ProjectNameSDK.test(seed, { feature: { streaming: { active: true } } })
-      const got = []
-      for await (const item of sdk.EntityName().stream('list')) {
-        if (Array.isArray(item)) { got.push(...item) } else { got.push(item) }
-      }
-      assert.equal(got.length, 3)
-    }
-  })
-
-
   test('basic', async () => {
     // <[SLOT:basic]>
   })

package/project/.sdk/src/cmp/kotlin/EntityTypes_kotlin.ts

@@ -0,0 +1,200 @@
+
+// Typed-model generator (Kotlin target). Port of EntityTypes_java.ts /
+// EntityTypes_py.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits ONE file, core/<Name>Types.kt,
+// holding a container `object <Name>Types` with a nested `data class` per
+// active entity plus a request/match type per active op.
+//
+// WHY A CONTAINER OBJECT: parity with the java/csharp emitters — every
+// generated reference type lives inside a single `object <Name>Types`, so the
+// whole reference model is in one file (<Name>Types.kt) whatever the entity
+// count. Kotlin has no one-public-type-per-file rule, but the single-file
+// convention is kept for cross-language consistency.
+//
+// TYPE CHOICE: reference types with BOXED (nullable) component types, NOT the
+// wired runtime type. The generated ops take/return the loose object model
+// (MutableMap<String, Any?> / Any?), so these types are NOT wired into the op
+// signatures — they are documentation/DX reference shapes a caller may use to
+// describe a payload before converting it to a map. This mirrors the JS
+// target's JSDoc typedefs (annotation only, no runtime effect). Emitting unused
+// types is harmless — they compile and have no runtime effect.
+//
+// OPTIONAL FIELDS: every component is a nullable reference type, so a
+// `req:false` field/param needs no distinct rendering in Kotlin.
+//
+// EMPTY SHAPES: Kotlin forbids a `data class` with zero components, so an
+// empty shape is emitted as a plain marker `class <Name>` instead.
+//
+// Sentinels map to Kotlin types via the SHARED canonToType 'kotlin' column
+// (the single source of truth per language — do not keep a local table here).
+//
+// Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch (via the shared opTypeName helper).
+
+import {
+  cmp, each, names,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { kotlinPackage } from './utility_kotlin'
+
+
+// Kotlin hard keywords that cannot be a (non-escaped) property name.
+const KOTLIN_KEYWORDS = new Set<string>([
+  'as', 'break', 'class', 'continue', 'do', 'else', 'false', 'for', 'fun',
+  'if', 'in', 'interface', 'is', 'null', 'object', 'package', 'return',
+  'super', 'this', 'throw', 'true', 'try', 'typealias', 'typeof', 'val',
+  'var', 'when', 'while',
+])
+
+
+// A field/param name that has a safe Kotlin identifier rendering. Names that
+// are not valid identifiers (hyphens, leading digits) have no clean component
+// form and are skipped — they remain reachable via the runtime map.
+function kotlinIdent(name: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !KOTLIN_KEYWORDS.has(name)
+}
+
+
+const LANG = 'kotlin'
+
+
+// Emit a nested `data class <typeName>(...)` from {name, type} items. An item
+// whose name is not a legal identifier is skipped (WITH a warning — the key
+// stays reachable via the runtime map, but its absence from the typed model
+// should be visible, not silent); a duplicate component name (after the
+// identifier filter) is dropped. An empty shape becomes a plain marker
+// `class <typeName>` (Kotlin forbids a zero-component data class).
+function emitRecord(typeName: string, items: any[], log?: any): void {
+  const seen = new Set<string>()
+  const usable = items.filter((it: any) => {
+    if (!it || null == it.name) {
+      return false
+    }
+    if (!kotlinIdent(it.name)) {
+      if (log && log.warn) {
+        log.warn({
+          point: 'entity-types-skip-field', typeName, field: it.name,
+          note: `kotlin: field "${it.name}" of ${typeName} has no legal ` +
+            `Kotlin identifier form; omitted from the typed model (still ` +
+            `reachable via the runtime map)`,
+        })
+      }
+      return false
+    }
+    if (seen.has(it.name)) {
+      return false
+    }
+    seen.add(it.name)
+    return true
+  })
+
+  if (0 === usable.length) {
+    Content(`  class ${typeName}
+
+`)
+    return
+  }
+
+  const params = usable
+    .map((it: any) => `val ${it.name}: ${canonToType(it.type, LANG)}`)
+    .join(', ')
+  Content(`  data class ${typeName}(${params})
+
+`)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model, log } = props.ctx$
+  const target = props.target || {}
+  const ext = target.ext || 'kt'
+
+  const kotlinpackage = props.kotlinpackage || kotlinPackage(model)
+
+  // only_active:false — getModelPath DROPS active:false entries by default,
+  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
+  // collection, so inactive entities still get generated entity code that
+  // references these typed names. The typed model must cover them too.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  // Emit for EVERY entity that gets generated entity code: the consumer
+  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
+  // filter, so inactive entities still get class files referencing these
+  // typed names. Filter on `name` (always present), NOT `active` — parity
+  // with the go emitter's fix.
+  const entityList = deriveEntityNames(entity)
+  // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
+  // entity not yet named (e.g. a fieldless placeholder) would otherwise read
+  // `Name = undefined` below. Parity with the go/py/csharp/java emitter's fix.
+
+  // Surface duplicate generated type names (two entities with the same
+  // PascalCase Name) — they would redeclare a type in statically-typed
+  // targets. Detection only; renaming is a model-level decision.
+  warnEntityTypeCollisions(entity, log, LANG)
+
+  File({ name: model.const.Name + 'Types.' + ext }, () => {
+
+    Content(`package ${kotlinpackage}.core
+
+// Typed reference models for the ${model.const.Name} SDK.
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params (op.<name>.points[].args.params[]). Field/param types come from the
+// canonical type sentinels (source of truth: @voxgig/apidef VALID_CANON). Do
+// not edit by hand.
+//
+// These types are documentation/DX reference shapes ONLY. The SDK ops take and
+// return the loose object model (MutableMap<String, Any?> / Any?) at runtime,
+// so these types are not wired into the op signatures — use them to describe a
+// payload before converting it to a map. Every component is a nullable type, so
+// an optional (req:false) key needs no distinct rendering.
+
+@Suppress("unused")
+object ${model.const.Name}Types {
+
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one component per field.
+      emitRecord(Name, fields.map((f: any) => ({
+        name: f.name, type: f.type,
+      })), log)
+
+      // Per active op: a request/match type. Members come from the shared
+      // partiality policy (opRequestShape).
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        emitRecord(typeName, items, log)
+      })
+    })
+
+    Content(`}
+`)
+  })
+})
+
+
+export {
+  EntityTypes,
+}