@voxgig/sdkgen 4.21.0 → 4.22.0

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

@@ -32,8 +32,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     if (!exampleEntity || !primaryOp) return ''
     if ('list' === primaryOp) return ''
     if (isMatchOp) {
-      // 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))

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

@@ -10,11 +10,6 @@ import {
 import { exampleValue } from './utility_js'
 
 
-// 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))
@@ -26,7 +21,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
-  // Find the first published entity for examples
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
   const ctor = isAuthActive(model)
@@ -47,8 +41,6 @@ const client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
-    // ACTIVE ops only — an inactive op generates no method, so an example
-    // calling it would be wrong.
     const opnames = entityOps(exampleEntity)
 
     // Model-driven example fields, in parity with the ts target: derive the
@@ -57,20 +49,13 @@ const client = ${ctor}
     // `idF` is the entity's id-like field name, or null when it has none —
     // 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 = 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
-      // incomplete).
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
           ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
       const optional = items.filter((it: any) => it.optional)
-      // create needs ALL required fields for parity with the typed ts target;
-      // update is a patch, so the required members plus a sample optional
-      // field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))

package/project/.sdk/src/cmp/js/ReadmeRef_js.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, opRequestShape, safeVarName, exampleVarName, jsKey , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -44,7 +44,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -185,7 +185,6 @@ Alias for \`${model.Name}SDK.test()\`.
       // Model-driven id key: null when this entity has no id-like field, in
       // 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 = exampleVarName(ent.name, 'js')
 
       Content(`
@@ -208,7 +207,6 @@ const ${eVar} = client.${ent.Name}()
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -406,9 +404,6 @@ const client = new ${model.Name}SDK({
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }
 

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

@@ -10,11 +10,6 @@ import {
 import { exampleValue } from './utility_js'
 
 
-// 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))
@@ -41,8 +36,6 @@ const client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     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)
 
     if (opnames.includes('list')) {

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

@@ -12,27 +12,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
-//
-// Two exports, both struct.validate specs:
-//
-//   OPTSPEC     what makeOptions validates the caller's options against —
-//               the standard options from `main.kit.optspec` plus one entry
-//               per feature this target carries, built by helpers/optspec.
-//
-//   ENTITYSPEC  per entity, `{ data, op: { <opname> } }` — the record shape
-//               and each operation's request shape, mapped from the field
-//               type sentinels the model already carries (helpers/canonSpec).
-//               Emitted as an EMPTY MAP unless the `validate` feature is
-//               active, because nothing else reads it and every byte here is
-//               a byte in the consumer's package.
-//
-// A JSON OBJECT LITERAL, not a parsed string: JSON is a subset of the
-// language's own literal syntax, so the values land as data with no parse
-// step, and the backticks the sentinels carry (`\`$STRING\``) survive because
-// JSON.stringify quotes and escapes them. The config emitter has to choose
-// between a literal and a parsed blob because the config can be megabytes;
-// the spec is bounded by the model's field count, so it does not.
 const Schema = cmp(async function Schema(props: any) {
   const ctx$ = props.ctx$
   const target = props.target

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

@@ -22,6 +22,7 @@ import {
   jsProp, envName, envToken,
   jsKey,
   pointParts,
+  hasLiveScenarios,
 } from '@voxgig/sdkgen'
 
 
@@ -52,16 +53,6 @@ const TestDirect = cmp(function TestDirect(props: any) {
       apikey: env.${PROJECTNAME}_APIKEY,`
     : ''
 
-  // A templated server URL (OpenAPI server variables) makes a LIVE client
-  // impossible to construct without values: makeOptions raises rather than
-  // request a URL with a literal `{account_id}` in it. Taken from the
-  // environment, the same way the apikey is.
-  //
-  // Keys are quoted and the env read is bracketed via jsKey/jsProp: a server
-  // variable name is spec-derived and need not be a JS identifier — the URL
-  // grammar admits a leading digit ({2fa}), and a declared-but-unreferenced
-  // variable ({edge-zone}) is not constrained at all. Bare `name:` and
-  // `env.PROJ_SERVER_EDGE-ZONE` are both syntax errors.
   const svars = serverVariables(model)
   const serverEnvEntry = svars
     .map((v: any) => `\n    '${serverVarEnv(PROJECTNAME, v.name)}': ${JSON.stringify(v.dflt)},`).join('')
@@ -96,7 +87,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
         Slot({ name: 'directSetup' }, () => {
           Content(`
-function liveScenariosActive() { return ${Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live)))} && process.env.${PROJECTNAME}_TEST_LIVE === 'TRUE' }
+function liveScenariosActive() { return ${hasLiveScenarios(model)} && process.env.${PROJECTNAME}_TEST_LIVE === 'TRUE' }
 function directSetup(mockres) {
   const calls = []
 
@@ -389,11 +380,6 @@ ${varAsserts}    }
 }
 
 
-// Replace raw OpenAPI parameter names in path parts with model parameter names.
-// Path parts may have e.g. {subBreed} while model params use sub_breed.
-// When a rename mapping exists (e.g. closureId -> id), path parts contain the
-// renamed form {id} but params still use the original name closure_id.
-// The rename mapping is used to reverse-lookup the original param name.
 function normalizePathParams(
   parts: string[],
   params: any[],

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

@@ -34,7 +34,8 @@ import {
   serverVariables,
   entityDataIdField, envName, envToken,
   jsKey,
-  jsProp
+  jsProp,
+  hasLiveScenarios,
 } from '@voxgig/sdkgen'
 
 
@@ -74,16 +75,6 @@ const TestEntity = cmp(function TestEntity(props: any) {
         apikey: env.${PROJENVNAME}_APIKEY,`
     : ''
 
-  // A templated server URL (OpenAPI server variables) makes a LIVE client
-  // impossible to construct without values: makeOptions raises rather than
-  // request a URL with a literal `{account_id}` in it. So the live suite
-  // takes them from the environment the same way it takes the apikey.
-  //
-  // Keys are quoted and the env read is bracketed via jsKey/jsProp: a server
-  // variable name is spec-derived and need not be a JS identifier — the URL
-  // grammar admits a leading digit ({2fa}), and a declared-but-unreferenced
-  // variable ({edge-zone}) is not constrained at all. Bare `name:` and
-  // `env.PROJ_SERVER_EDGE-ZONE` are both syntax errors.
   const svars = serverVariables(model)
   const serverEnvEntry = svars
     .map((v: any) => `\n    '${serverVarEnv(PROJENVNAME, v.name)}': ${JSON.stringify(v.dflt)},`).join('')
@@ -93,7 +84,6 @@ const TestEntity = cmp(function TestEntity(props: any) {
           ${jsKey(v.name)}: ${jsProp('env', serverVarEnv(PROJENVNAME, v.name))},`).join('')}
         },`
 
-  // TODO: should be a utility function
   const ff = projectPath('src/cmp/js/fragment/')
 
   Folder({ name: entity.name }, () => {
@@ -219,7 +209,7 @@ function basicSetup(extra) {
           )
 
           Content(`
-    ${Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live))) ? `if (process.env.${PROJENVNAME}_TEST_LIVE === 'TRUE') { t.skip('Covered by live operation scenarios'); return }` : ''}
+    ${hasLiveScenarios(model) ? `if (process.env.${PROJENVNAME}_TEST_LIVE === 'TRUE') { t.skip('Covered by live operation scenarios'); return }` : ''}
     const setup = basicSetup()
     if (setup.live) {
       return runLiveEntity(setup, ${JSON.stringify(entity)}, ${JSON.stringify(basicflow)}, '${nom(entity, 'Name')}')

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

@@ -1,4 +1,4 @@
-import { cmp, File, Content, entityCollection, envName, serverVariables, serverVarEnv } from '@voxgig/sdkgen'
+import { cmp, File, Content, entityCollection, envName, serverVariables, serverVarEnv, liveHint, pointFacts } from '@voxgig/sdkgen'
 import { nom } from '@voxgig/apidef'
 
 const TestLive = cmp(function TestLive(props: any) {
@@ -8,11 +8,18 @@ const TestLive = cmp(function TestLive(props: any) {
     if (entity.active === false) continue
     for (const [op, operation] of Object.entries(entity.op || {}) as any[]) {
       for (const point of operation.points || []) {
-        const facts = point.contract ? JSON.parse(point.contract.json) : {}
+        // Only what the runner reads; see the ts component.
+        const all: any = pointFacts(props.ctx$, point)
+        const facts: any = {
+          live: liveHint(point),
+          security: all.security,
+          securitySource: all.securitySource,
+          responses: all.responses,
+        }
         if (model.main.kit.info?.auth === false) facts.security = []
         const same = operation.points.filter((p: any) => JSON.stringify(p.select || {}) === JSON.stringify(point.select || {}))
         plan.push({ entity: entity.name, accessor: nom(entity, 'Name'), op,
-          id: point.contract?.id || point.method + ' ' + point.orig, contractVersion: point.contract?.version, kind: point.kind, graphql: point.graphql, path: point.orig, method: point.method,
+          id: point.contract?.id || point.method + ' ' + point.orig, contractVersion: point.contract?.version ?? 1, kind: point.kind, graphql: point.graphql, path: point.orig, method: point.method,
           action: point.select?.$action, rename: point.rename, args: point.args, facts, reachable: same.length === 1 })
       }
     }

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

@@ -15,35 +15,12 @@ import {
 } from '@voxgig/struct'
 
 
-// --- Model-driven example literals -----------------------------------------
-// Doc snippets must use example values whose TYPE matches the generated
-// types, or the snippet misrepresents the API. The id/match params of
-// load/remove/update are the common trap: their generated
-// `<Name><Op>Match` / `<Name><Op>Data` type is built from the op's params
-// (see EntityTypes_js.ts), so a numeric id shown as a quoted string is
-// wrong. These helpers derive the example literal from the SAME model
-// source, so the docs and the generated types can never disagree.
 
 // The declared canon-type sentinel of a named parameter of an op — looked up
 // in the op's `points[].args.params[]` exactly as the typed-model generator
 // does. Falls back to the entity field of the same name (used when the op
 // has no params). Returns undefined when neither is present.
 function paramCanonType(entity: any, op: any, paramName: string): unknown {
-  // opParams, NOT a raw walk of op.points.
-  //
-  // opParams drops points flagged with select['$action'] and merges what is
-  // left; the typed-model generator reaches the op's params through it, so
-  // anything else is a DIFFERENT set of params wearing the same name.
-  //
-  // A raw walk returned the first match on ANY point, action points included.
-  // github's `action` entity has a field `owner` (`$OBJECT`, "A GitHub user")
-  // and seven create points whose path carries `{owner}` (a string) — so the
-  // type said Record<string, any> and the doc example said 'example_owner',
-  // and ts/README.md stopped compiling. Same for workflow_id: `number` in the
-  // type, quoted string in the example.
-  //
-  // Deriving from opParams is what actually makes good on the promise below —
-  // that the docs and the generated types cannot disagree.
   const params = op ? each(opParams(op)) : []
   const found = (params as any[]).find((p: any) => p && p.name === paramName)
   if (found) {
@@ -55,11 +32,6 @@ function paramCanonType(entity: any, op: any, paramName: string): unknown {
 }
 
 
-// A type-correct example literal for a named match/data parameter of an op,
-// derived entirely from the model. INTEGER/NUMBER render as the bare number
-// `1`, BOOLEAN as `true`, ARRAY as the empty `[]` and OBJECT as the empty
-// `{}`, everything else (STRING, unknown, missing) as the quoted
-// `placeholder`.
 function exampleValue(entity: any, op: any, paramName: string, placeholder: string): string {
   // canonScalarKey, not canonKey: a nullable field's sentinel is the union
   // ['`$ONE`', ['`$NUMBER`','`$NULL`']], which canonKey stringifies into
@@ -105,17 +77,14 @@ function formatJson(obj: any, flags?: { line?: boolean, margin?: number }): stri
   let json: string
 
   if (flags?.line) {
-    // One line with spaces for clarity
     json = JSON.stringify(obj)
       .replace(/([{:\[,])/g, '$1 ')
       .replace(/([}\]])/g, ' $1')
   }
   else {
-    // Pretty printed with 2-space indentation
     json = JSON.stringify(obj, null, 2)
   }
 
-  // Add margin to the left of every line
   if (marginSize > 0) {
     json = json.split('\n').map(line => marginStr + line).join('\n')
   }
@@ -124,41 +93,14 @@ function formatJson(obj: any, flags?: { line?: boolean, margin?: number }): stri
 }
 
 
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
 const MODEL_META = ['index$', 'key$', 'val$']
 
-// Keys whose value IS the default the runtime already assumes when the key is
-// absent, so emitting them is pure payload.
 const CONFIG_DEFAULT: Record<string, any> = {
   active: true,
   req: false,
   reqd: false,
 }
 
-// Subtrees carrying user payload rather than schema. An active:true inside an
-// OpenAPI example is DATA, not a default, so default-pruning stops at these
-// keys and everything below them is passed through untouched.
 const PAYLOAD_KEYS = ['default', 'example', 'examples']
 
 function clean(o: any, dropDefaults?: boolean): any {

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

@@ -40,9 +40,6 @@ const Config = cmp(async function Config(props: any) {
   const kotlinpackage = kotlinPackage(model)
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Gated by the applicability tags, so this target never imports or
-  // registers a feature it has no source for. One rule, one place:
-  // helpers/applicability.
   const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
@@ -50,24 +47,12 @@ const Config = cmp(async function Config(props: any) {
   const authActive = isAuthActive(model)
   const authPrefix = resolveAuthPrefix(model)
   const authBasic = isHttpBasicAuth(model)
-  // `in` and `name` travel with the prefix now. apidef resolved both all
-  // along, into main.kit.info.security, and this emitter dropped them - so
-  // an apiKey-in-query API got an Authorization header it does not read.
-  // The generated utility/PrepareAuth.kt is built from the same two values.
-  //
-  // Emitted only when they DIFFER from the defaults, so a
-  // header/Authorization SDK's Config.kt is byte-identical to what it
-  // generated before.
   const authIn = resolveAuthIn(model)
   const authName = resolveAuthName(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
-  // Identity comes from configDefinition's def, not re-derived here, so
-  // this target cannot disagree with the shared emitter on main.slug /
-  // main.version / main.target (the three station descriptor fields,
-  // station design §4) — passing target.name is what opts this target in.
   const { def: configDef } = configDefinition(model, target.name)
 
   // The feature block comes from configDefinition's def, not from
@@ -101,48 +86,17 @@ const Config = cmp(async function Config(props: any) {
   options.headers = headers
   options.entity = optionsEntity
 
-  // configDefinition's `def.entity` verbatim, NOT rebuilt here. This reduce
-  // was one of fourteen copies of that function's entityDefs loop, and when
-  // configDefinition started reconstructing a point's `parts` from apidef's
-  // segment vector (its ADR-003), only the copies that read `configDef` got
-  // it — this target's literal config emitted paths with no parts at all
-  // while its data config had them. One rule, one place.
   const entityConfig = configDef.entity
 
-  // THE PLUGIN DEFINITIONS the model selected, per feature.
-  //
-  // sekreto's contract since the registry was retired: a kind not passed
-  // in `plugins` is unknown to that Sekreto, so the model's choice of
-  // plugin groups IS the SDK's provider vocabulary. This walks the
-  // catalogue's active `plugin.def.kotlin` entries and hands the list to
-  // the feature through `Config.featurePlugins`.
-  //
-  // Kotlin's Definition symbols are PLAIN TOP-LEVEL VALS
-  // (`val hashicorp: Definition = providerplugin("hashicorp") {...}`), so
-  // the def key is the val name and the import is that name qualified by
-  // the file's package - DERIVED from the def path (`feature/secrets/
-  // sekreto/plugins/Hashicorp.kt` -> `feature.secrets.sekreto.plugins`)
-  // rather than hardcoding `secrets`, exactly as the go emitter does.
-  //
-  // Emitted in core, which already names KOTLINPACKAGE.feature classes in
-  // makeFeature - Kotlin has no package-cycle rule, so nothing here can
-  // introduce one. The feature reads it back as List<Any?> and filters by
-  // type, so a tree with the feature present but no group selected still
-  // compiles with no import at all.
   const pluginImports = new Set<string>()
   const featurePlugins: Record<string, string[]> = {}
 
   each(feature, (f: any) => {
     const syms: string[] = []
     each(f.plugin, (plugin: any) => {
-      // Filter on `active` HERE rather than trusting the feature object to
-      // arrive filtered: getting this wrong emits an import for a file the
-      // plugin trim just deleted, and the SDK does not compile.
       if (false === plugin.active || null == plugin.active) return
       for (const [sym, one] of Object.entries(plugin.def?.kotlin || {})) {
         const dir = String(one).replace(/\/[^/]+$/, '').replace(/\//g, '.')
-        // A dotted symbol (another language's class-qualified spelling)
-        // imports its HEAD; kotlin's own keys are bare val names.
         pluginImports.add(
           kotlinpackage + '.' + dir + '.' + String(sym).split('.')[0])
         syms.push(sym)

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

@@ -29,8 +29,6 @@ const EntityOperation = cmp(function Operation(props: any) {
       EntityName: entity.Name,
       entityname: entity.name,
 
-      // Class tokens are decoupled from the EntityName data-type token so the
-      // class can be renamed independently (collision handling).
       EntyClass: cls,
 
       '#Feature-Hook': ({ name, indent }: any) =>

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

@@ -1,38 +1,4 @@
 
-// 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,
@@ -58,9 +24,6 @@ const KOTLIN_KEYWORDS = new Set<string>([
 ])
 
 
-// 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)
 }
@@ -69,12 +32,6 @@ function kotlinIdent(name: string): boolean {
 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) => {
@@ -122,10 +79,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 
   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
@@ -137,9 +90,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // 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 }, () => {
@@ -169,13 +119,10 @@ object ${model.const.Name}Types {
       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]) {

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

@@ -43,10 +43,6 @@ const Entity = cmp(function Entity(props: any) {
 
       const opnames = Object.keys(entity.op || {})
 
-      // For each CRUD op: if the spec defines it, splice in the real
-      // implementation. Otherwise emit a stub that satisfies the SdkEntity
-      // interface (so the package compiles) but errors at runtime if the
-      // caller invokes an unsupported op.
       const opfrags =
         (['load', 'list', 'create', 'update', 'remove']
           .reduce((a: any, opname: string) =>

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

@@ -51,62 +51,17 @@ const Main = cmp(async function Main(props: any) {
   // token used throughout the templates (package/import statements).
   Copy({
     from: 'tm/' + target.name,
-    // pluginExcludes: the generate-time plugin trim (an INACTIVE plugin
-    // group's declared files stay out of the tree - the model's `path`
-    // entries are target-root-relative, which is this Copy's root). Without
-    // it every plugin group ships regardless of the model and the def maps
-    // decide nothing; an exclude that matches nothing is indistinguishable
-    // from no exclude at all, which is how this went wrong before.
     exclude: [/src\//, TEST_CONTROL_EXCLUDE, ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
       KOTLINPACKAGE: kotlinpackage,
 
-      // The vendored sekreto port carries upstream's own package root, and
-      // a generated SDK must not publish classes in it: a Maven artifact
-      // declaring `com.voxgig.sekreto` collides with the real library on
-      // any consumer classpath. It would not COMPILE either - the vendor
-      // route's `adapt` for this library matches only Sekreto.kt and
-      // Support.kt, so the other fifteen sekreto files still declare
-      // `package com.voxgig.sekreto` while those two moved, and every
-      // cross-file reference is unresolved.
-      //
-      // Done HERE, the way Main_go rewrites the placeholder
-      // `github.com/voxgig/struct` import, because this Copy is the one
-      // seam every vendored file crosses on its way into an SDK. It is a
-      // NO-OP for a file the vendor route already rewrote, so widening
-      // that route's `adapt.match` to the whole `feature/secrets/`
-      // directory simply retires this line.
-      //
-      // (The sibling `voxgig.plugin` rewrite is NOT needed: that route's
-      // adapt already matches the whole `feature/secrets/plugin/` tree,
-      // and the token appears nowhere in tm/kotlin. A replace that matches
-      // nothing is indistinguishable from no replace at all, so it is not
-      // carried "just in case".)
       'com.voxgig.sekreto': kotlinpackage + '.feature.secrets.sekreto',
     }
   })
 
-  // Shared entity runtime (entity/EntityBase.kt).
   EntityBase({ target })
 
-  // utility/PrepareAuth.kt. GENERATED, NOT COPIED: where the credential
-  // goes - header, query parameter or cookie, under the name the spec gives
-  // - is a fact about the API, and tm/ can only hold one answer. It was
-  // embedded in tm/kotlin/utility/Prepare.kt among the other prepare*
-  // helpers, hardcoding an `authorization` header; that one function has
-  // moved out into its own compilation unit in the same package, so
-  // Register.kt's `u.prepareAuth = ::prepareAuth` binds it unchanged.
-  //
-  // Called HERE, at Main's TOP LEVEL, and deliberately NOT inside the
-  // `core` Folder below. The kotlin tree is FLAT: build.gradle.kts declares
-  // core/, utility/, feature/ and entity/ as four sibling source roots, and
-  // the Copy above lands tm/kotlin/utility/* at <out>/utility/. The
-  // component opens `utility` itself, exactly as EntityBase opens `entity`.
-  // Nested in `core` it would write core/utility/PrepareAuth.kt - which
-  // still COMPILES, because core/ is scanned recursively and the package
-  // declaration is what resolves the symbol, so the misfiling would be
-  // invisible to every check. See PrepareAuth_kotlin.
   PrepareAuth({ target })
 
   // Generate the client class and config in core/.
@@ -126,7 +81,6 @@ const Main = cmp(async function Main(props: any) {
           }
         },
 
-        // Entities - injected at SLOT
         () => {
           each(entity, (entity: ModelEntity) => {
             const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)