@voxgig/sdkgen 4.20.0 → 4.22.0

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

@@ -22,6 +22,7 @@ import {
 
 import { Package } from './Package_kotlin'
 import { Config } from './Config_kotlin'
+import { Schema } from './Schema_kotlin'
 import { Gitignore } from './Gitignore_kotlin'
 import { MainEntity } from './MainEntity_kotlin'
 import { EntityBase } from './EntityBase_kotlin'
@@ -50,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/.
@@ -125,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}`)
@@ -136,6 +91,7 @@ const Main = cmp(async function Main(props: any) {
     })
 
     Config({ target })
+    Schema({ target })
 
     // Generate the typed reference-model file (<Name>Types.kt) beside the
     // other generated core files. Documentation/DX shapes only — not wired

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

@@ -15,39 +15,6 @@ import {
 import { kotlinPackage } from './utility_kotlin'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated.
-//
-// apidef has always resolved the scheme's `in` and `name` into
-// `main.kit.info.security` — joplin's says `in: "query", name: "token"` —
-// and generation dropped both, hardcoding an `authorization` header. The
-// result was an SDK that sent a header the API does not read and never
-// sent the query parameter it does, so it could not authenticate at all.
-// Four repos in the cedar fleet shipped that way: joplin (`token`),
-// pipedrive (`api_token`), trello (`key`), lm-umbrella (`apiKey`).
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value that is fixed at
-// generation time. The ts port (PrepareAuth_ts) is the donor.
-//
-// KOTLIN IS AN EXTRACTION, NOT A REPLACEMENT. The other twelve targets had
-// a `prepare_auth` template of their own to delete; kotlin did not — the
-// function lived among eight unrelated `prepare*` helpers in
-// `tm/kotlin/utility/Prepare.kt`. So `prepareAuth` (and only it, with the
-// three constants nothing else in that file used) MOVES here, into its own
-// compilation unit in the SAME package.
-//
-// That is a pure move as far as every caller is concerned, because a
-// Kotlin top-level function is visible to the whole package without an
-// import: `utility/Register.kt` keeps binding `u.prepareAuth = ::prepareAuth`
-// unchanged, `core/Utility.kt` keeps its `lateinit var prepareAuth:
-// (Context) -> Spec` and its `u.prepareAuth = this.prepareAuth` copy, and
-// `core/SdkClient.kt` and `utility/MakeSpecUrl.kt` keep calling
-// `utility.prepareAuth(ctx)` through that binding. Nothing is renamed and
-// nothing is re-wired. The three constants were `private` (file-scoped), so
-// carrying them here cannot collide with what stays behind.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -56,46 +23,13 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
 
   const where = resolveAuthIn(model)
 
-  // LOWERCASED FOR A HEADER, VERBATIM OTHERWISE. `spec.headers` is a
-  // LinkedHashMap<String, Any?> — case-SENSITIVE — and every other writer
-  // and reader of an auth header in this target spells it lower case: the
-  // deleted template's own `HEADER_AUTH = "authorization"`, SecretsFeature's
-  // `headers["authorization"]` rewrite and removal, DebugFeature's redact
-  // list, PipelineTest's assertions, and the shared corpus's
-  // `ctx:spec:headers:authorization`. apidef writes `name: "Authorization"`,
-  // so emitting it verbatim would put the credential under a key none of
-  // those touch — a second header beside the one they manage rather than
-  // the one they manage. Header names are case-insensitive on the wire
-  // (RFC 7230) and lower case on HTTP/2, so nothing is lost. Query
-  // parameters and cookies ARE case-sensitive and keep the spec's spelling.
   const resolved = resolveAuthName(model)
   const name = 'header' === where ? resolved.toLowerCase() : resolved
 
   const basic = isHttpBasicAuth(model)
 
-  // Read so the resolution is visible at generation time even though the
-  // emitted code takes the prefix from options at runtime (the secrets
-  // feature rewrites it there).
   const prefix = resolveAuthPrefix(model)
 
-  // FOLDER NESTING, worked out from the template's own path and from
-  // Main_kotlin's call site.
-  //
-  // Main_kotlin's `Copy({ from: 'tm/kotlin', exclude: [/src\//] })` runs at
-  // Main's TOP LEVEL, so `tm/kotlin/utility/Prepare.kt` lands at
-  // `<out>/utility/Prepare.kt` — and `build.gradle.kts` declares
-  // `sourceSets["main"].kotlin.setSrcDirs(listOf("core", "utility",
-  // "feature", "entity"))`, four SIBLING roots at the target root. So this
-  // component opens exactly ONE segment, `utility`, and Main must call it
-  // from its top level — NOT from inside `Folder({ name: 'core' })`, where
-  // Config and SdkError are written.
-  //
-  // Nested there it would write `core/utility/PrepareAuth.kt`, and that
-  // mistake is INVISIBLE to a compile: `core` is itself a source root and
-  // gradle scans it recursively, so the misplaced file would still be
-  // compiled and its `package <pkg>.utility` declaration would still make
-  // `::prepareAuth` resolve. The tree would simply be wrong — a utility
-  // file filed under core — with nothing to report it.
   Folder({ name: 'utility' }, () => {
     File({ name: 'PrepareAuth.' + target.ext }, () => {
       Content(render({
@@ -122,31 +56,6 @@ type AuthSpec = {
 
 
 function render(spec: AuthSpec): string {
-  // NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING.
-  //
-  // `isAuthActive` answers two different questions with one boolean:
-  //
-  //   1. `main.kit.config.auth.active: false` — this SDK is deliberately
-  //      built WITHOUT auth. A per-SDK decision by the project.
-  //   2. `main.kit.info.auth: false`          — the SPEC declares no
-  //      security scheme. A fact about the API definition.
-  //
-  // Only (1) may silence prepareAuth. (2) says nothing about whether the
-  // CALLER holds a credential, and kotlin has always let one through: the
-  // optspec in `tm/kotlin/utility/MakeOptions.kt` supplies an
-  // `"auth": { "prefix": "" }` default whether or not the generated Config
-  // carries one, so `options["auth"]` is non-null at runtime, the
-  // template's `options["auth"] == null` guard never fired, and the
-  // credential was placed regardless of what the spec declared. The
-  // generated secrets feature depends on exactly that — it resolves a
-  // secret into `options.apikey` and expects prepareAuth to place it — and
-  // so does generatedcompile's `kotlin: auth null beats an explicit apikey`
-  // lane, whose baseline ("an ordinary apikey IS sent") is unsatisfiable
-  // the moment the wider gate is used.
-  //
-  // `isAuthSuppressed` is the narrow one: `main.kit.config.auth.active ===
-  // false` and nothing else. A spec that is merely silent keeps the
-  // credential path it has always had.
   if (spec.suppressed) {
     return head(spec) + `import ${spec.kotlinpackage}.core.Context
 import ${spec.kotlinpackage}.core.Spec
@@ -176,9 +85,6 @@ function head(spec: AuthSpec): string {
 }
 
 
-// The credential-absent test, identical in all three placements and
-// identical to the template's. Kept as one string so a placement cannot
-// drift from the others on what "no credential" means.
 const SKIP = `  var skip = false
   if (apikey == null) {
     skip = true
@@ -246,15 +152,6 @@ fun prepareAuth(ctx: Context): Spec {
 }
 
 
-// HTTP BASIC IS HEADER-ONLY BY DEFINITION: the scheme is
-// `Authorization: Basic base64(user:pass)`. It cannot be expressed as a
-// query parameter or a cookie, so the branch is emitted only from
-// renderHeader, and only when the model says this API actually uses it — a
-// bearer SDK carries none of it.
-//
-// `Struct.getpath` returns the UNDEF sentinel, not null, for a path the map
-// does not have, so the switch is read with `is Boolean` rather than
-// compared against `true`: the sentinel is neither.
 function basicBlock(spec: AuthSpec): string {
   if (!spec.basic) return ''
 
@@ -293,10 +190,6 @@ function basicBlock(spec: AuthSpec): string {
 }
 
 
-// QUERY. MakeSpecUrl fills `spec.query` (prepareQuery) BEFORE it calls
-// prepareAuth, and makeUrl reads `spec.query` afterwards, url-escaping every
-// key and value onto the URL — so the credential placed here reaches the
-// wire as `?name=value`. The headers are never touched.
 function renderQuery(spec: AuthSpec): string {
   return head(spec) + `import ${spec.kotlinpackage}.core.Context
 import ${spec.kotlinpackage}.core.Spec
@@ -339,12 +232,6 @@ fun prepareAuth(ctx: Context): Spec {
 }
 
 
-// COOKIE. A cookie IS a header, so the credential rides the header bag —
-// but the `cookie` header is SHARED with whatever cookies options.headers
-// (or an earlier feature) put there, so our pair is SPLICED in and out
-// rather than the header assigned over. Splicing also makes this
-// idempotent: a retried request cannot end up carrying the credential
-// twice.
 function renderCookie(spec: AuthSpec): string {
   return head(spec) + `import ${spec.kotlinpackage}.core.Context
 import ${spec.kotlinpackage}.core.Spec

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

@@ -11,7 +11,6 @@ import { kotlinVarName } from './utility_kotlin'
 
 // Type names come from the shared canonToType 'kotlin' column (single source of truth).
 
-// A type-correct Kotlin literal for a field's canonical type.
 function kotlinLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k) return '1L'

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

@@ -4,26 +4,6 @@ import { cmp, File, Content } from '@voxgig/sdkgen'
 import { kotlinPackage } from './utility_kotlin'
 
 
-// Emits test/ReadmeExamplesTest.kt — a JUnit PRESENCE + STRUCTURE gate over
-// every ```kotlin fenced block in the repository ROOT README.md, the
-// per-language kotlin/README.md, AND the per-language kotlin/REFERENCE.md.
-//
-// SCOPE NOTE (deliberate, documented): the Python/TS/Go equivalents EXECUTE and
-// type-check every documented block. That is infeasible here — the generated
-// Kotlin SDK compiles with Gradle/kotlinc only (no in-process Kotlin compiler
-// dependency wired into the test classpath), so a test cannot compile-and-run
-// arbitrary doc snippets at test time. This gate therefore guarantees the
-// weaker-but-real invariant that keeps the docs honest as the generator evolves:
-//   1. every doc exists and contains at least one ```kotlin block (nothing was
-//      dropped);
-//   2. every ```kotlin block is structurally well-formed — its braces,
-//      parentheses and brackets balance (catches a truncated or malformed
-//      generated snippet).
-// A per-doc summary line makes the coverage visible in the test output.
-//
-// The emitted Kotlin is written WITHOUT literal backticks (the fence marker is
-// built at runtime as 96.toChar().toString().repeat(3)) so this TS template
-// literal stays clean.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target, ctx$: { model } } = props
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -60,7 +60,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const SDK = model.const.Name + 'SDK'
 
   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)
 
@@ -377,9 +377,6 @@ val client = ${SDK}(mutableMapOf<String, Any?>("feature" to feature))
 \`\`\`
 
 `)
-      // 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/kotlin/ReadmeTopQuick_kotlin.ts

@@ -54,15 +54,10 @@ import ${kotlinPackage(model)}.core.${SDK}
   }
 
   if (exampleEntity) {
-    // Sanitise the local variable name — an entity whose camelCased name is a
-    // Kotlin keyword gets a trailing underscore (kotlinVarName) so the snippet
-    // compiles.
     const eVar = kotlinVarName(exampleEntity.name)
     const accessor = kotlinVarName(exampleEntity.name)
     const eNameLower = nom(exampleEntity, 'Name').toLowerCase()
     const opnames = Object.keys(exampleEntity.op || {})
-    // Model-driven id key: null when the entity has no id-like field, in which
-    // case the load example takes an empty match.
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {

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

@@ -0,0 +1,92 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  kotlinPackage,
+  jsonAppendLines,
+} from './utility_kotlin'
+
+
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+  const kotlinpackage = kotlinPackage(model)
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  // Beside Config.kt, and for the same reason: core owns the generated data,
+  // so nothing in utility or feature has to reach up for it.
+  File({ name: 'Schema.' + target.ext }, () => {
+
+    Content(`package ${kotlinpackage}.core
+
+import ${kotlinpackage}.utility.Json
+
+/**
+ * ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+ *
+ * Generated from the model: \`main.kit.optspec\` and each feature's
+ * \`config.options\` for the option spec; entity \`fields[].type\` for the
+ * entity specs.
+ */
+@Suppress("UNCHECKED_CAST")
+object Schema {
+
+  // Parsed ONCE, on first use. The spec is read on every client construction
+  // and never mutated, so a per-call parse would be pure waste — and a shared
+  // map is safe for the same reason the spec is a constant: makeOptions
+  // validates AGAINST it and writes into the options, never into the spec.
+  //
+  // 'by lazy' defaults to LazyThreadSafetyMode.SYNCHRONIZED, as
+  // Config.sharedConfig uses, so concurrent first calls parse it exactly once.
+
+  /** The option spec makeOptions validates client options against. */
+  val optspec: MutableMap<String, Any?> by lazy {
+    Json.parse(optspecJson()) as MutableMap<String, Any?>
+  }
+
+  /** Per-entity data and request specs, keyed by entity name. */
+  val entityspec: MutableMap<String, Any?> by lazy {
+    Json.parse(entityspecJson()) as MutableMap<String, Any?>
+  }
+
+  private fun optspecJson(): String {
+    val b = StringBuilder()
+`)
+
+    Content(jsonAppendLines(optspec, 'b'))
+
+    Content(`    return b.toString()
+  }
+
+  private fun entityspecJson(): String {
+    val b = StringBuilder()
+`)
+
+    Content(jsonAppendLines(entityspec, 'b'))
+
+    Content(`    return b.toString()
+  }
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

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

@@ -152,10 +152,6 @@ ${allSteps.length > 0 ? `    val client = setup.client\n\n` : ''}`)
 
 `)
 
-    // Stream test (PR #4): the entity `stream` method runs the op pipeline and
-    // returns a Sequence. With the streaming feature active it yields from the
-    // feature's incremental iterator; otherwise it falls back to the
-    // materialised items. Only emitted for entities whose flow lists.
     const flowHasList = allSteps.some((s: any) => s.op === 'list')
     if (flowHasList) {
       Content(`  @Test

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

@@ -24,12 +24,6 @@ const Test = cmp(function Test(props: any) {
     // Write-once: a project's edited control file survives regeneration.
     TestControl({ target, dir: 'test' })
 
-    // The shared test infrastructure (RunnerSupport, the vendored omni
-    // runner under test/vendor/omni with its OmniResolver/OmniSmokeTest,
-    // FeatureHarness, PipelineTest, FeatureTest, NetsimTest,
-    // PrimaryUtilityTest, CustomUtilityTest, StructCorpusTest, ExistsTest
-    // and sdk-test-control.json) ships as templates in tm/kotlin/test/ and
-    // is copied by Main_kotlin. Here we generate only the API-specific tests.
     const entity = each(entityCollection(model))
       .filter((e: any) => false !== e.active)
     each(entity, (entity: ModelEntity) => {

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

@@ -34,7 +34,6 @@ function kotlinPackage(model: any): string {
 }
 
 
-// Maven/Gradle group coordinates for the generated SDK (used by Package_kotlin).
 function gradleGroup(model: any): string {
   const org = String(model.origin || 'voxgig-sdk')
     .replace(/-sdk$/, '')
@@ -45,7 +44,6 @@ function gradleGroup(model: any): string {
 
 
 const KOTLIN_KEYWORDS = new Set([
-  // hard keywords
   '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',
@@ -53,9 +51,6 @@ const KOTLIN_KEYWORDS = new Set([
 ])
 
 
-// A camelCase Kotlin identifier for a snake_case model name
-// (`status_embed_config` -> `statusEmbedConfig`), with a reserved-word
-// guard (a `fun`/`class` entity must not bind a Kotlin keyword).
 function kotlinVarName(name: string): string {
   const pascal = camelify(name)
   const out = pascal.charAt(0).toLowerCase() + pascal.slice(1)
@@ -63,42 +58,14 @@ function kotlinVarName(name: string): string {
 }
 
 
-// Strip model bookkeeping keys (ending in $) from a config subtree.
-// 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 cleanModel(o: any, dropDefaults?: boolean): any {