v0.10.0 to v0.11.0

- version: 0.10.0

- description: |

- The Kotlin target-language layer for SKMTC generators

- (`@skmtc/lang-kotlin`). Covers how a generator declares Kotlin as its

- target language (importing `toKtModelProjectionBase` /

- `toKtOasOperationProjectionBase` and `KtSnippet` from the lang

- package), what the lang package exports (the `kotlin` Lang object,

- the register family, `KtFile` / `KtImport` / `KtDefinition`), the

- head+value rendering model, entity kinds and identifier factories,

- the import model of emitted Kotlin (packages from paths, symbol-level

- imports, same-package suppression, no type-only imports), the value

- composition classes (`KtParameterList`, `KtPrimaryConstructor`,

- `KtFunctionSignature`, `KtAnnotation`), the `SchemaToValueFn` router

- contract and where serialization annotations and default values are

- decided (inside the router's per-type snippets, exposed as value

- fields), and naming/sanitization (`sanitizePropertyName`,

- `toPackageName`, hard keywords like `object`).

-

- Use this skill alongside `skmtc-generator` whenever a generator emits

- Kotlin — and specifically when the user asks about "lang-kotlin",

- "KtSnippet", "data class generation", "sealed interface", "package

- directive", "backticks", "@SerialName"/"@JsonProperty" wiring,

- "KtAnnotation", or anything about the *shape of the emitted Kotlin*

- rather than engine behavior. Engine rules (Projections, Snippets,

- cross-generator coordination, variants) live in `skmtc-generator`.

- allowed-tools:

- - Bash

- - Read

- - Glob

- - Grep

- - Write

- - Edit

- # SKMTC Kotlin language layer

-

- This skill covers the **target-language** side of generator authoring:

- what the emitted Kotlin looks like and which package owns each piece.

- The boundary rule, worth internalizing first:

-

- > **The authoring language is always TypeScript/Deno; only the target

- > language varies.** Rules about how generator *source* is written

- > (`as` casts, `switch`+`never`, Valibot enrichments) live in

- > `skmtc-generator`. This skill covers how the generator's *output* is

- > shaped — files, packages, imports, declarations, naming — for

- > generators whose target is Kotlin.

-

- This skill follows the `skmtc-lang-<X>` template established by

- `skmtc-lang-typescript`: the same seven section headings, with Kotlin's

- answers. Read §2 first if you read only one section — the **head +

- value rendering model** is the intuition every other rule falls out of.

-

- ## 1. Package surface

- `@skmtc/lang-kotlin` exports:

- | Export | What it is |

- |---|---|

- | `kotlin` | The `Lang` object. Three neutral factories the engine's **Drivers** call, reading it ephemerally off the projection class's inherited static (`projection.lang`): `createFile`, `toDefinition`, `toImport` (+ the identifier-assembly seam `toIdentifier`). Generators never call it |

- | `KtSnippet` | The snippet base — where Kotlin enters the DSL class hierarchy. Carries the static `lang`; its `register` / `defineAndRegister` methods are typed by the concise vocabulary. Registering snippets are **keyless** (`generatorKey` is optional attribution input) and always pass an explicit `destinationPath` |

- | `toKtModelProjectionBase` / `toKtOasOperationProjectionBase` | The projection-base veneers over core's factories — pre-bind `KtSnippet` as the factory's positional first argument and add own-file `register(args)` + explicit cross-file `registerInto(destinationPath, args)`. The config is core's `ModelProjectionBaseConfig<E, KtIdentifierType>` (etc.), so `toIdentifierType`'s return is compile-time bound to Kotlin's entity kinds |

- | `register` / `defineAndRegister` | The register **functions** — convert the concise form, create the destination `KtFile` on first write, hand pure data to the neutral `context.register`. Transforms (closures with no class) import `defineAndRegister` directly. `register` throws on a cross-language file collision |

- | `KtRegisterArgs` / `KtDefineAndRegisterArgs` | The concise register vocabulary: `imports` / `definitions` / `custom` (leading file content — see §3). Deliberately **no `reExports` field**: Kotlin has no re-exports, so a generator registering one is a compile-time error, not a runtime no-op |

- | `KtFile` | `CodeFileBase` subclass — a Kotlin output file. Derives its `package` directive from its own export path (§5), sorts imports alphabetically, suppresses same-package imports, renders the `custom` slot above the `package` line |

- | `KtImport` / `KtImportNameArg` / `KtImportSpecifier` | `ImportBase` subclass — symbol-level import statements with `as` aliases; no brace grouping, no type-only form (§3) |

- | `KtDefinition` | `DefinitionBase` subclass — renders `${head}${value}` (declaration kinds) or `${head} = ${value}` (assignment kinds), plus the value-carried `KtAnnotated` / `KtDocumented` protocols above the line (§2, §4) |

- | `KtIdentifier` / `isKtIdentifier` / `KtIdentifierType` / `KtIdentifierArgs` | Kotlin's concrete `IdentifierBase`: carries the typed `type: KtEntityType` and renders its own **declaration head** — `[private ]<keyword> <name>[: <typeName>]` |

- | `createClass` / `createDataClass` / `createEnumClass` / `createInterface` / `createSealedInterface` / `createTypeAlias` / `createValue` | The identifier factories — one per entity kind (§2) |

- | `KtEntityType` / `isKtEntityType` / `toKtEntityType` | The entity-kind vocabulary, its guard, and the throw-narrowing of the engine's opaque `type` string |

- | `KtParameterList` | Primary-constructor parameter list, **parentheses included** (§4) |

- | `KtPrimaryConstructor` | Constructor modifiers + the explicit `constructor` keyword rule (§4) |

- | `KtFunctionSignature` / `KtFunctionParameter` | Method signatures for interface/class bodies — annotations, KDoc, expression bodies, parameter defaults (§4) |

- | `KtAnnotation` / `KtAnnotations` / `toKtAnnotations` / `KtAnnotated` | Annotation rendering + the self-registering import (§3, §4) |

- | `KtDocumented` / `isKtDocumented` | The value-carried KDoc protocol (§4) |

- | `withDescription` | Wraps a rendered declaration in a KDoc comment block |

- | `sanitizePropertyName` | Kotlin/JVM property-name sanitization — backtick escaping, hard keywords (§5) |

- | `toPackageName` | `@/`-export-path → dotted package, with segment validation (§5) |

- | `ktHardKeywords` / `isKtIdentifierName` | The validation primitives behind the two above |

- | `langId` | `'kotlin'` |

- | `fileExtensions` | `['.kt']` |

- ### Wiring — the import graph declares the language

- ```ts fragment

- // gen-x/src/base.ts — the language enters HERE, through the import

- import { toKtModelProjectionBase } from '@skmtc/lang-kotlin'

- import { emptyEnrichmentSchema } from '@skmtc/core'

- import denoJson from '../deno.json' with { type: 'json' }

- export const KtModelBase = toKtModelProjectionBase({

- // Pure — the cache-key name. For DTO generators the refName IS the class name.

- toIdentifierName: ({ refName }) => refName,

- // Context-aware — the declaration kind, derived from the schema on cache-miss.

- // Return type is KtIdentifierType: `type` is compile-checked against §2's vocabulary.

- toIdentifierType: (refName, context) => {

- const schema = context.resolveSchemaRefOnce(refName, denoJson.name)

- return { type: schema.type === 'object' ? 'data-class' : 'typealias' }

- // The export path doubles as the package — `@/models/…` → `package models` (§5).

- toExportPath: ({ refName }) => `@/models/${refName}.generated.kt`,

- toEnrichmentSchema: () => emptyEnrichmentSchema

- })

- ```

-

- ```ts fragment

- // gen-x/src/KtModel.ts — the per-schema Projection

- import type { EmptyEnrichments, ModelProjectionArgs, Stringable } from '@skmtc/core'

- import { KtAnnotation } from '@skmtc/lang-kotlin'

- import { KtModelBase } from './base.ts'

- import { toKtValue } from './Kt.ts'

-

- export class KtModel extends KtModelBase {

- // Class-level annotations — the KtAnnotated protocol (§4). The Driver

- // wraps THIS instance in the Definition, so the projection IS the

- // definition's value and the protocol field lives directly on it:

- // KtDefinition reads it as `this.value.annotations`.

- annotations: KtAnnotation[]

- value: Stringable

-

- // The enrichment generic must match the base: `toEnrichmentSchema:

- // () => emptyEnrichmentSchema` makes the base expect

- // ModelProjectionArgs<EmptyEnrichments>; the bare default fails

- // `deno check` — which bundle/generate will NOT catch (esbuild does

- // not typecheck).

- constructor({ context, settings, refName }: ModelProjectionArgs<EmptyEnrichments>) {

- super({ context, settings, refName })

-

- const schema = context.resolveSchemaRefOnce(refName, KtModel.id).resolve()

-

- // ONE router call — the generator's SchemaToValueFn owns every

- // schema.type decision (skmtc-generator axiom 1); 'object' maps to

- // the data-class value snippet inside the router, not here.

- this.value = toKtValue({

- context,

- schema,

- destinationPath: settings.exportPath, // snippets/leaves always get the parent's file

- required: true

- })

-

- // Reference-sharing: point the protocol field at the routed value's

- // OWN array — one array, two names; whatever a router case put there

- // is already here. Push projection-level policy into it; NEVER

- // reassign it afterward (a later `this.annotations = []` would

- // silently split the two names onto different arrays).

- this.annotations = this.value.annotations

- this.annotations.push(

- new KtAnnotation({

- context,

- name: 'JsonIgnoreProperties',

- args: ['ignoreUnknown = true'],

- packageName: 'com.fasterxml.jackson.annotation',

- destinationPath: settings.exportPath

- })

- )

- }

-

- toString(): string {

- return `${this.value}`

- }

- }

- ```

-

- ```ts fragment

- // gen-x/src/mod.ts — the entry is pure pipeline config; no language anywhere

- import { toModelEntry } from '@skmtc/core'

- import denoJson from '../deno.json' with { type: 'json' }

- import { KtModel } from './KtModel.ts'

-

- export const ktModelEntry = toModelEntry({

- id: denoJson.name,

- transform({ context, refName }) {

- context.insertModel(KtModel, refName)

- toEnrichmentSchema: () => emptyEnrichmentSchema

- })

- ```

-

- A generator declares its language **only** by importing its

- projection-base veneer (and, for registering snippets, `KtSnippet`)

- from this package. The language rides the class hierarchy as the

- static `lang` on `KtSnippet`; the engine's Drivers read it ephemerally

- off the projection class when they need to create a file or build a

- Definition. Nothing else changes versus a TypeScript generator: the

- same entry factories, the same engine calls — `insertModel(Peer,

- refName)` for a named `$ref`, `insertNormalizedModel(Peer, { schema,

- fallbackName })` for a schema that may be inline or a ref,

- `findDefinition` to read the cache — the same `ContentSettings`. All

- engine-side, all in `skmtc-generator`; do not re-derive them from core

- source.

-

- Generators normally never construct `KtFile` / `KtDefinition` /

- `KtImport` directly — this package's register functions and the

- engine's Drivers build them. If you find yourself writing

- `new KtImport(...)` in a generator, you almost certainly wanted

- `this.register({ imports })`.

-

- The package dependency (both required, **same `lang-kotlin` pin in

- every package of the stack** — see §6):

-

- ```jsonc

- // gen-x/deno.json#imports

- {

- "@skmtc/core": "jsr:@skmtc/core@<pin>",

- "@skmtc/lang-kotlin": "jsr:@skmtc/lang-kotlin@<pin>"

- }

- ```

-

- The same-pin rule covers **core too**: pin `@skmtc/core` to the exact

- version the lang-kotlin package (vendored or JSR) pins — read it from

- that package's `deno.json` rather than taking a newer one. Two core

- copies in one build break cross-copy `instanceof` exactly like two

- lang copies (§6).

-

- ### The router contract — `SchemaToValueFn`, no core dive needed

-

- The `toKtValue` router the scaffold above calls is typed by core's

- `SchemaToValueFn`. Its whole surface:

-

- ```ts fragment

- type SchemaType = OasSchema | OasRef<'schema'> | OasVoid | CustomValue

-

- type SchemaToValueFn = <S extends SchemaType>(

- args: TypeSystemArgs<S>

- ) => TypeSystemOutput<S['type']>

-

- type TypeSystemArgs<S extends SchemaType> = {

- context: GenerateContextType

- destinationPath: string // the parent's file — threaded into every leaf

- schema: S // the typed variant after narrowing

- rootRef?: RefName // originating ref name, when routing a named schema

- required: boolean | undefined

- }

- ```

-

- The contract is **structural**: each per-type snippet class carries the

- fields of its output type alongside its own state — nothing extends a

- core class for this. The `skmtc create … --lang kotlin` skeleton's

- `DataClassValue` is the worked case: `type = 'object' as const`,

- `recordProperties: null`, `objectProperties`, `modifiers`. A snippet

- for another schema type carries its own output type's fields the same

- way (`'string'` → `type`, `format`, `enums`, `modifiers`).

-

- The complete output-shape crib — **exact**, one line per contract

- type; a snippet carries its case's fields verbatim (each shape also

- takes an optional `generatorKey`; `enums` keeps its full Nullable

- union — §4):

-

- ```ts fragment

- type TypeSystemString = { type: 'string'; format: string | undefined; enums: string[] | (string | null)[] | undefined; modifiers: Modifiers }

- type TypeSystemInteger = { type: 'integer'; modifiers: Modifiers }

- type TypeSystemNumber = { type: 'number'; modifiers: Modifiers }

- type TypeSystemBoolean = { type: 'boolean'; modifiers: Modifiers }

- type TypeSystemArray = { type: 'array'; items: TypeSystemValue; modifiers: Modifiers }

- type TypeSystemRef = { type: 'ref'; name: string; modifiers: Modifiers }

- type TypeSystemObject = { type: 'object'; recordProperties: TypeSystemRecord | null; objectProperties: TypeSystemObjectProperties | null; modifiers: Modifiers }

- type TypeSystemRecord = { value: TypeSystemValue | 'true' }

- type TypeSystemObjectProperties = { properties: Record<string, TypeSystemValue> }

- type TypeSystemUnion = { type: 'union'; members: TypeSystemValue[]; discriminator: string | undefined; modifiers: Modifiers }

- type TypeSystemUnknown = { type: 'unknown' }

- type TypeSystemCustom = { type: 'custom'; value: Stringable }

- ```

-

- Two more facts that save a dive into `core/types/TypeSystem.ts`:

-

- - **`Modifiers` is deliberately thin** — `{ required?, description?,

- nullable? }` and nothing else. Wire facts (`readOnly` / `writeOnly`,

- `format`) are NOT threaded through modifiers; the per-type snippet

- holds its typed schema variant and reads them directly (§4,

- "annotations and defaults are decided inside the per-type snippet").

- - **Keep the router's plain signature** (§4: union in, union out,

- intersected with `KtValueFields`) — the generic

- `TypeSystemOutput<S['type']>` tightening is documented there as a

- rare exception, not the default.

-

- The output types carry `.type` discriminators, but consumers never

- need them (§4): a renderer reads fields off routed values —

- `annotations`, `defaultValue` — instead of narrowing.

-

- ## 2. Entity kinds & identifiers

-

- Kotlin output has seven entity kinds (`KtEntityType`), created via the

- identifier factory functions exported by this package. **The identifier

- renders its own declaration head; the value renders everything after

- it.** `KtDefinition` composes the two without inspecting either:

-

- ```text

- declaration kinds: ${head}${value} class | data-class | enum-class | interface | sealed-interface

- assignment kinds: ${head} = ${value} typealias | val

- ```

-

- | Factory | Head rendered | The value then renders |

- |---|---|---|

- | `createClass('UsersService')` | `class UsersService` | `${primaryConstructor}${supertypeClause}${body}` |

- | `createDataClass('User')` | `data class User` | `${parameterList}${supertypeClause}` |

- | `createEnumClass('Status')` | `enum class Status` | ` {\n ACTIVE,\n …\n}` |

- | `createInterface('UsersApi')` | `interface UsersApi` | ` {\n${signatures}\n}` |

- | `createSealedInterface('Animal')` | `sealed interface Animal` | usually nothing — the bodyless idiom |

- | `createTypeAlias('UserList')` | `typealias UserList` | the right-hand side (`List<User>`) |

- | `createValue('timeout', { typeName: 'Long' })` | `val timeout: Long` | the right-hand side expression |

-

- The consequences, each a rule you'd otherwise rediscover:

-

- - **A value's `toString()` starts where the head ends.** For a data

- class that means the parameter list (parens included, §4); for an

- enum/interface it means the braced body *including* the leading

- ` {`; for a sealed interface it is typically the empty string —

- an empty render IS how `sealed interface Animal` gets its bodyless

- form. Never render the keyword, the name, or `data class` inside a

- value.

- - **Visibility is the identifier's fact.** Kotlin defaults to public,

- so `exported: true` (the default) renders nothing and

- `createDataClass('User', { exported: false })` renders

- `private data class User`. There is no `noExport` on this package's

- definition/register args — the neutral Driver-level `noExport` flag

- is folded into a restricted identifier copy at the `Lang.toDefinition`

- boundary, and in-generator code passes `exported: false` to the

- factory instead.

- - **The `typeName` slot is the `val x: T` annotation** — only

- `createValue` takes it. It is part of the head, not the value.

- - `isKtIdentifier` narrows a neutral `IdentifierBase` back to

- `KtIdentifier`; `toKtEntityType` / `isKtEntityType` narrow the

- engine's opaque `type` string. Generators rarely call either — the

- veneer's `ModelProjectionBaseConfig<E, KtIdentifierType>` makes

- `toIdentifierType`'s return compile-checked, and a foreign

- identifier fails loudly at the Generate boundary.

- - Unlike TypeScript, the entity kind does **not** drive import form —

- every Kotlin import is `import pkg.Name`. It drives only the

- declaration shell. Kinds not yet in the vocabulary (`object`, `fun`,

- `var`) arrive with the milestones that need them; `toKtEntityType`

- throwing on them is the desired behavior until then.

-

- ## 3. The import model of emitted Kotlin

-

- Generators register imports in the concise form (`KtImportNameArg`);

- the register function converts them to `KtImport`s at the boundary:

-

- ```ts fragment

- this.register({

- imports: {

- // dotted package — external libraries

- 'com.fasterxml.jackson.annotation': ['JsonProperty', 'JsonSubTypes'],

- // @/-export path — project files (rarely hand-written: the Driver

- // registers peer imports for you on insertModel/insertOperation)

- '@/models/Role.generated.kt': ['Role'],

- // symbol-level alias — Kotlin's `as`

- 'kotlinx.serialization.json': [{ name: 'Json', alias: 'KJson' }]

- Rendering rules `KtFile` / `KtImport` apply (authors never hand-write

- these):

-

- - **One statement per symbol** (`import kotlinx.serialization.Serializable`)

- — Kotlin has no brace grouping. Imports render **sorted

- alphabetically**, so registration order cannot leak into output.

- - **No type-only imports.** `KtImportNameArg` has no `type` tag —

- the TS1484 discipline from lang-typescript has no Kotlin

- counterpart. If you find yourself tagging imports, you're writing a

- TypeScript instinct into a Kotlin generator.

- - **Path-form modules resolve to packages at render.**

- `'@/models/Role.generated.kt'` → `import models.Role` via

- `toPackageName` (§5). The Driver passes exactly this form for

- cross-file peer imports.

- - **Same-package imports are suppressed centrally.** A symbol in the

- destination file's own package needs no import in Kotlin, and

- `KtFile` drops it at render. Over-registering is therefore harmless

- — callers never need a same-package check. The single-file

- consequence: in a generator that registers every model into ONE

- file (the DTO-file idiom), peer references need **no import wiring

- at all** — get the peer's name through the `insertModel` handle

- (`.toName()`, per `skmtc-generator` §4) and interpolate it; there

- is no circular-import hazard to design around, since Kotlin

- same-file declarations reference each other freely. Concretely, the

- router's whole `ref` case is those two calls: a `RefValue` snippet

- whose constructor does `context.insertModel(KtModel,

- ref.toRefName())` and whose `toString()` returns the stored

- `.toName()` — no register, nothing else.

- - **Importing from the default package throws.** Kotlin cannot import

- a root-level (package-less) symbol from a packaged file; hitting

- this means a generator's path policy put an artifact at `@/<Name>.kt`

- that packaged files reference — give the artifact a package path.

- - **Re-exports don't exist.** No barrels, no `reExports` field. The

- absence is compile-time by design.

-

- ### Annotation imports — the self-registering leaf

-

- The dominant import in generated Kotlin is an annotation class.

- `KtAnnotation` makes the annotation and its import **one statement**

- (the `TsHeritage` registering-leaf pattern), so they cannot drift

- apart:

-

- ```ts fragment

- new KtAnnotation({

- context,

- name: 'JsonProperty',

- args: ['"user_id"'],

- packageName: 'com.fasterxml.jackson.annotation', // self-registers the import

- destinationPath // always explicit — the parent knows its file

- })

- // renders: @JsonProperty("user_id")

- // registers: import com.fasterxml.jackson.annotation.JsonProperty

- ```

-

- Omit `packageName` for default-scope annotations (`@Deprecated`,

- `@Suppress` — `kotlin.*` needs no import): the annotation then only

- renders. Never pair a `KtAnnotation` with a separate manual

- `register({ imports })` for the same class (§6).

-

- Multi-element `args` render comma-joined on **one line**

- (`args.join(', ')`). For a multi-line annotation body — the

- `@JsonSubTypes` idiom with one `JsonSubTypes.Type(…)` entry per

- line — pass a SINGLE arg carrying the whole body: a `Stringable`

- snippet whose `toString()` composes the lines (keeping composition

- inside `toString()`), or a pre-formatted string.

-

- The self-registration covers the annotation's **own** class only.

- When the annotation's *arguments* name a second symbol —

- `@JsonSerialize(using = MoneyStringSerializer::class)`,

- `@field:JsonDeserialize(using = MoneyStringDeserializer::class)` —

- that symbol needs its own `register({ imports })` alongside the

- annotation (the args are opaque `Stringable`s; nothing parses class

- references out of them). One annotation, two imports. Exception:

- when the referenced class lands in the destination file's own

- package, same-package suppression (§3) makes the extra register

- unnecessary — though registering it anyway is harmless.

-

- ### Leading file content — the `custom` slot

-

- `KtRegisterArgs.custom` sets the destination file's neutral `custom`

- slot (`FileBase.custom`), rendered **above the `package` directive**

- (only comments may precede `package` in Kotlin) — e.g. a

- generated-file attribution banner. Same placement and semantics as

- `TsFile`: last non-`undefined` write wins.

-

- ## 4. Syntax helpers

-

- The composable value classes a declaration-kind value interpolates.

- All return `Stringable`-compatible values that compose in template

- literals; **plain Kotlin syntax carries no grammar rule worth a

- class**, so supertype clauses (` : Animal`) and braced bodies

- (` {\n…\n}`) are written inline in the value's `toString()`.

-

- | Helper | Renders | The grammar rule it owns |

- |---|---|---|

- | `KtParameterList` | `(\n @Anno\n val id: String,\n val email: String? = null\n)` | Parentheses included; each parameter a `val` property with annotations one per line above it, `private/protected/internal` visibility, `?` nullability, ` = default` |

- | `KtPrimaryConstructor` | `(…)` or ` @Anno private constructor(…)` | Modifiers force Kotlin's explicit `constructor` keyword; without modifiers it renders just the parameter list |

- | `KtFunctionSignature` | ` @GetMapping("/users/{id}")\n fun getUsersId(@PathVariable("id") id: String): User` | Method signatures inside interface/class bodies: per-signature KDoc + annotations, abstract by default, expression body via `body` (` = …` — block bodies deliberately unsupported), implicit `Unit` when `returnType` omitted |

- | `KtFunctionParameter` | `@RequestParam("verbose") verbose: Boolean? = null` | One signature parameter — annotations, nullability, defaults |

- | `KtAnnotations` (via `toKtAnnotations(value)`) | One annotation per line + trailing newline; empty renders `''` | The class-level annotation block above a declaration |

- | `withDescription(value, { description })` | `/** … */\n${value}` | KDoc — Kotlin's block-comment syntax is JSDoc-identical; multi-line descriptions get ` * ` margins |

-

- The exact constructor shapes — **these are complete**, and the

- **generated API appendix** (`appendix.md`, this skill's directory)

- carries the full `deno doc` surface of the whole package (every

- export, exact argument shapes, generated from source — it cannot

- drift). Between this section and that file there is nothing left to

- learn from pre-reading the package source; verify with `deno check`

- after scaffolding instead:

-

- ```ts fragment

- // KtParameterList — new KtParameterList(parameters: KtParameterArgs[])

- type KtParameterArgs = {

- name: string // FINAL name — already sanitized, may be backticked

- type: Stringable

- nullable?: boolean // renders `Type?`

- defaultValue?: Stringable // renders ` = …` (e.g. 'null')

- annotations?: KtAnnotation[] // inline, before `val`

- visibility?: 'private' | 'protected' | 'internal' // absent = public

- }

-

- // KtAnnotation — new KtAnnotation(args: KtAnnotationArgs)

- type KtAnnotationArgs = {

- context: GenerateContextType

- name: string

- args?: Stringable[] // pre-quoted, rendered inside `(…)`; omitted → bare @Name

- packageName?: string // self-registers the import; omit for kotlin.* scope

- destinationPath: string // always explicit — the parent knows its file

- }

-

- // KtFunctionSignature — new KtFunctionSignature(args)

- type KtFunctionSignatureArgs = {

- name: string

- parameters: KtFunctionParameterArgs[] // { name, type, nullable?, defaultValue?, annotations? }

- returnType?: Stringable // omitted → implicit Unit

- annotations?: KtAnnotation[]

- description?: string // KDoc above the annotations

- body?: Stringable // expression body ` = …`; absent → abstract form

- }

-

- // KtPrimaryConstructor — new KtPrimaryConstructor(args)

- type KtPrimaryConstructorArgs = {

- parameters: Stringable // typically a KtParameterList (owns its parens)

- modifiers?: Stringable[] // e.g. annotations / 'private' — forces `constructor` keyword

- }

-

- // Identifier factories — createDataClass(name, { exported?: boolean })

- // (all kinds; only createValue adds { typeName?: string })

- ```

-

- ```text

- data class value: `${parameterList}${supertypes.length ? ` : ${supertypes.join(', ')}` : ''}`

- class value: `${primaryConstructor} : ${supertype} {\n${body}\n}`

- enum class value: ` {\n ${members.join(',\n ')}\n}`

- interface value: ` {\n${signatures.join('\n\n')}\n}`

- sealed interface: `` ← the bodyless idiom

- typealias / val: the right-hand-side expression

- ```

-

- ### Exact render shapes — verbatim

-

- Generated by constructing each class and printing `toString()` —

- match output against these instead of reading the rendering source

- (`«»` marks the exact boundaries; every newline and space is real):

-

- ```text

- createDataClass('User') «data class User»

- createDataClass('User', { exported: false }) «private data class User»

- createValue('timeout', { typeName: 'Long' }) «val timeout: Long»

- createSealedInterface('Animal') «sealed interface Animal»

-

- KtAnnotation { name: 'JsonProperty', args: ['"user_id"'] }

- «@JsonProperty("user_id")»

- KtAnnotation { name: 'JvmInline' } «@JvmInline»

-

- toKtAnnotations(value) — one per line + TRAILING newline (so

- `${annotations}${head}` needs no separator); empty renders «»:

- «@JsonProperty("user_id")

- @Deprecated("use v2")

- »

-

- KtParameterList — parens included, one param per line at 4-space

- indent, annotations one per line ABOVE their param, inline

- visibility; an EMPTY list renders parens around a blank line:

- «(

- @JsonProperty("user_id")

- val userId: String,

- private val name: String,

- val email: String? = null

- )» empty: «(

-

- )»

-

- KtPrimaryConstructor — without modifiers, identical to its parameter

- list; with modifiers, a LEADING space then the explicit keyword:

- « private constructor(…)»

-

- KtFunctionSignature — indented 4 spaces (it lives inside a

- declaration body); single-line KDoc stays inline; parameters on one

- line; expression body appends ` = …`:

- « /** Fetch one user. */

- @GetMapping("/users/{id}")

- fun getUsersId(id: String, verbose: Boolean? = null): User»

- « fun toId(raw: String): UserId = UserId(raw)»

-

- KtDefinition (declaration kind) — KDoc, then annotations, then

- `${head}${value}` with no space before the value's parens:

- «/** A user of the system. */

- @JsonSerialize(…)

- data class User(

- …

- )»

- KtDefinition (assignment kind) «typealias UserList = List<User>»

-

- withDescription(value, { description }) — MULTI-line descriptions get

- a block with ` * ` margins (single-line stays inline as above):

- «/**

- * Line one.

- * Line two.

- */

- data class X(…)»

- ```

-

- ### The `oneOf` → sealed interface recipe

-

- The Kotlin idiom for a discriminated `oneOf` (`Animal` = `Dog | Cat`,

- discriminated by `petType`) is a sealed parent plus supertyped

- members. The pattern: **the union assigns membership to its members**

- — a member schema does not know it is in a union and behaves as if it

- is not.

-

- - **Members** carry two fields the parent writes to, both reachable

- through `inserted.definition.value` (the Driver wraps the projection

- instance itself in the Definition, so that IS the member

- projection): `supertypes` — declared on the projection, rendered by

- its own `toString()` — and the routed value's `parameters` array,

- reached as `.value.parameters` (it lives on the object value that

- renders it; no projection property, no copy). The router keeps the

- **bare `SchemaToValueFn` type** — nothing extra is threaded in;

- facts flow *out* of the router on the values it returns:

-

- ```ts fragment

- // Member side — the §1 projection, grown one seam. A schema that is

- // in no union renders exactly as before (supertypes empty).

- export class KtModel extends KtModelBase {

- supertypes: Stringable[] = []

- annotations: KtAnnotation[] // the KtAnnotated protocol slot (§4)

- value: ReturnType<typeof toKtValue> // NOT Stringable — so .value reads type-check

-

- constructor({ context, settings, refName }: ModelProjectionArgs<EmptyEnrichments>) {

- super({ context, settings, refName })

- const schema = context.resolveSchemaRefOnce(refName, KtModel.id).resolve()

- this.value = toKtValue({

- context,

- schema,

- destinationPath: settings.exportPath,

- required: true

- })

- // Reference-sharing: KtDefinition reads annotations off THIS

- // object, so the protocol slot must exist here — point it at the

- // routed value's own array (one array, two names; whatever a

- // router case put there is already here). Never reassign either

- // name afterward — push, don't replace.

- this.annotations = this.value.annotations

- }

-

- toString(): string {

- return `${this.value}${this.supertypes.length ? ` : ${this.supertypes.join(', ')}` : ''}`

- }

- }

- ```

-

- The discriminator tag property is **removed by the parent, during

- generate** — not filtered at render: `insertModel` guarantees the

- member's constructor has run (existence), so the object value and

- its `parameters` array always exist by the time a union case

- touches them, whichever visit order; the `KtParameterList` built in

- the value's constructor holds the same array instance, so the

- removal is visible at render with zero render-time work. The member

- never chooses between tags (a member of two unions gets two

- removals); which tag appears on the wire is decided at

- serialization time by the sealed parent the value is viewed through

- (each parent renders its own `@JsonTypeInfo(property = …)`), never

- by the member.

-

- - **Parent**: `createSealedInterface(refName)` with a value whose

- `toString()` renders `''` — the bodyless idiom gives

- `sealed interface Animal`. The router case stays ONE line — `case

- 'union': return new UnionValue({ context, unionSchema: schema,

- destinationPath, rootRef, modifiers: { required } })` — like every

- other case: the router routes and constructs, it never does the

- work. The work all happens in **`UnionValue`'s constructor**: it

- receives the union facts (discriminator name, member list) with the

- typed schema, so it is where the parent's class annotations are

- decided — pushed into its own `annotations` array; the parent

- projection's alias line (previous fragment) makes that same array

- its `KtAnnotated` protocol slot. No annotation helper elsewhere, no

- `.type` guard anywhere. Membership assignment in a constructor is

- exactly axiom 2 — declaration at construction. Member assignment

- uses `insertModel` — it returns the one memoized handle however

- many producers ask, and `.definition.value` is the member

- projection instance — typed as such by `insertModel`'s generics, so

- the writes below need no cast:

-

- ```ts fragment

- // UnionValue, in full: the router case constructs it; the

- // constructor owns parent annotations + membership; toString

- // renders the bodyless idiom.

- export class UnionValue extends KtSnippet {

- type = 'union' as const

- members: (TypeSystemValue & KtValueFields)[]

- discriminator: string | undefined

- modifiers: Modifiers

- annotations: KtAnnotation[] = []

-

- constructor({ context, unionSchema, destinationPath, rootRef, modifiers }: Args) {

- super({ context })

- this.modifiers = modifiers

- this.discriminator = unionSchema.discriminator?.propertyName

- // Members route back through the router — the contract fields

- // come for free, and insertModel below is idempotent whether

- // reached from here or from the membership loop.

- this.members = unionSchema.members.map(member =>

- toKtValue({ context, schema: member, destinationPath, required: true })

- )

-

- const tag = this.discriminator

- if (tag) {

- // Wire tag per member: the discriminator mapping keys are the

- // wire values, the ref suffix identifies which member each

- // maps to; a member absent from the mapping defaults to its

- // refName.

- const mapping = unionSchema.discriminator?.mapping ?? {}

- const entries = unionSchema.members.flatMap(member => {

- if (!member.isRef()) return []

- const refName = member.toRefName()

- const wireTag =

- Object.entries(mapping).find(([, ref]) => ref.endsWith(`/${refName}`))?.[0] ?? refName

- return [{ className: refName, wireTag }]

- })

- this.annotations.push(

- new KtAnnotation({

- context,

- destinationPath,

- name: 'JsonTypeInfo',

- args: [`use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "${tag}"`],

- packageName: 'com.fasterxml.jackson.annotation'

- }),

- new KtAnnotation({

- context,

- destinationPath,

- name: 'JsonSubTypes',

- // ONE arg carrying the whole multi-line body (§3) — a tiny

- // dedicated snippet, so the composition lives in ITS

- // toString(), not built ad hoc here.

- args: [new SubTypeEntries({ context, entries })],

- packageName: 'com.fasterxml.jackson.annotation'

- })

- )

- }

-

- unionSchema.members.forEach(member => {

- if (!member.isRef()) return

- const inserted = context.insertModel(KtModel, member.toRefName())

- if (rootRef) inserted.definition.value.supertypes.push(rootRef)

- if (tag) {

- // Remove the tag parameter — Jackson owns it via the parent's

- // @JsonTypeInfo. Generate-time mutation of the object value's

- // entries array; its KtParameterList sees the settled result.

- const parameters = inserted.definition.value.value.parameters ?? []

- const at = parameters.findIndex(parameter => parameter.wireName === tag)

- if (at >= 0) parameters.splice(at, 1)

- }

- })

- }

-

- override toString(): string {

- return '' // the bodyless idiom — the head IS the declaration

- }

- }

- ```

-

- ```ts fragment

- // SubTypeEntries.ts — the multi-line @JsonSubTypes body as its own

- // tiny snippet. This is the canonical shape for ANY multi-line,

- // multi-symbol annotation argument: facts in the constructor,

- // composition in toString().

- export class SubTypeEntries extends KtSnippet {

- entries: { className: string; wireTag: string }[]

-

- constructor({ context, entries }: SubTypeEntriesArgs) {

- super({ context })

- this.entries = entries

- }

-

- override toString(): string {

- return this.entries

- .map(({ className, wireTag }) => `JsonSubTypes.Type(value = ${className}::class, name = "${wireTag}")`)

- .join(',\\n ')

- }

- }

- ```

-

- A note on the structural eval's composition metric: constructor-built

- annotation args (the `KtAnnotation` args above, an enum constant's

- `@JsonProperty("${wireValue}")`) count toward

- composition-outside-`toString()` — that is expected and fine.

- Annotations are BUILT at construction by design; the metric's 50%

- warning threshold accounts for this, so do not restructure working

- code just to move that number.

-

- - **Order cannot matter**: inserts are idempotent and memoized, so

- member-first and union-first visits converge on one instance, and

- generate completes before render — pinned by core's

- `GenerateContext.insert-mutation.test.ts`. Assign during generate

- only; `toString()` stays a pure read of the seams. Multi-union

- membership composes (` : A, B`) for free.

- - This is generator-owned state, NOT a lang protocol — the old

- `KtSupertyped` render protocol stays gone. The

- `skmtc create … --lang kotlin` scaffold is a deliberate skeleton

- and does NOT ship this pattern — this section is the canonical

- recipe; implement it in your generator.

-

- ### The `enum class` recipe — head and body from two seams

-

- **`enums` is not a string fact.** Every schema variant except `union`

- and `unknown` carries it, each over its own element type — integer and

- number enums (`enums: number[] | (number | null)[]`), boolean, array,

- object. This recipe covers the string case because that is the one

- that maps cleanly onto a Kotlin `enum class` with wire values; the

- others need a policy decision you make deliberately (an integer enum

- can be an `enum class` whose constants carry an `Int`, or just `Int`

- with the constraint dropped). Decide it in the router case that owns

- that type — a `number` snippet that silently ignores `enums` has made

- the decision by omission, and the schema's constraint vanishes with no

- trace.

-

- A string-with-`enums` schema becomes `enum class PetType { … }`, and

- the declaration is split across the two places §2 defines: the

- **identifier** renders the head (`enum class PetType`), so

- `toIdentifierType` must return `'enum-class'` — a mapping-metadata

- policy, where inspecting the schema is sanctioned:

-

- ```ts fragment

- // base.ts — declaration KIND is metadata (toIdentifierType may

- // inspect the schema; it decides what a node is CALLED, never what

- // renders it).

- toIdentifierType: (refName, context): KtIdentifierType => {

- const schema = context.resolveSchemaRefOnce(refName, denoJson.name).resolve()

- if (schema.type === 'object') return { type: 'data-class' }

- if (schema.type === 'union') return { type: 'sealed-interface' }

- if (schema.type === 'string' && schema.enums) return { type: 'enum-class' }

- return { type: 'typealias' }

- }

- ```

-

- The **value** renders the braced body — the router's `string` case

- forks on `enums` presence (a schema fact; the same within-case

- license as the `format` branch and the object case's Map fork):

-

- ```ts fragment

- case 'string':

- return schema.enums

- ? new EnumClassValue({ context, stringSchema: schema, destinationPath, modifiers })

- : new StringValue({ context, stringSchema: schema, destinationPath, modifiers })

- ```

-

- ```ts fragment

- // Renders ONLY the body — ` {\n…\n}` including the leading space and

- // braces (§2: the value owns its shell; the head comes from the

- // identifier). Everything is decided and built in the constructor:

- // wire value → UPPER_SNAKE constant name, the @JsonProperty rename

- // each constant keeps, and which constant gets @JsonEnumDefaultValue

- // (the forward-compatible fallback — generator policy).

- export class EnumClassValue extends KtSnippet {

- type = 'string' as const // TypeSystem contract fields (§1) …

- format: string | undefined

- enums: string[] | undefined

- modifiers: Modifiers

- annotations: KtAnnotation[] = [] // KtValueFields — empty here

- constants: { annotations: KtAnnotation[]; name: string }[]

-

- constructor({ context, stringSchema, destinationPath, modifiers }: Args) {

- super({ context })

- this.format = stringSchema.format

- this.enums = (stringSchema.enums ?? []).flatMap(entry => (entry === null ? [] : [entry]))

- this.modifiers = modifiers

- this.constants = this.enums.map(wireValue => ({

- // Wire values are data; constant names are identifiers.

- name: wireValue.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase(),

- annotations: [

- new KtAnnotation({

- context,

- destinationPath,

- name: 'JsonProperty',

- args: [`"${wireValue}"`],

- packageName: 'com.fasterxml.jackson.annotation'

- })

- ]

- }))

- }

-

- override toString(): string {

- const body = this.constants

- .map(({ annotations, name }) => `${annotations.map(a => ` ${a}\n`).join('')} ${name},`)

- .join('\n\n')

- return ` {\n${body}\n}`

- }

- }

- ```

-

- One caveat to state rather than discover: an **inline** (property-

- level) string-with-enums also routes through this case, and a braced

- body is not a valid property type. In the discriminated-union shape

- this is harmless — the only inline enums are discriminator tags,

- whose parameter entries the union parent removes before render. A

- schema with genuine inline enums needs a policy decision first: hoist

- the enum to a named schema (`insertNormalizedModel` with a

- `fallbackName`) or degrade the property to plain `String`.

-

- ### The value protocols — what renders *above* the declaration

-

- The neutral `Lang.toDefinition` call the Drivers make has no

- annotations or description slot, so both ride on the **value** and

- `KtDefinition` collects them at render:

-

- - **`KtAnnotated`** — a value with an `annotations: KtAnnotation[]`

- field. `toKtAnnotations(value)` collects it into a `KtAnnotations`

- block rendered one-per-line above the head.

- - **`KtDocumented`** (guard: `isKtDocumented`) — a value with a

- `description?: string` field, rendered as KDoc above the

- annotations. An explicit `description` passed to `KtDefinition` /

- `defineAndRegister` wins over the protocol.

-

- Both protocols are read off the **definition's value** —

- `thing.value.annotations` / `thing.value.description` — and that is

- the only place they live. For a `defineAndRegister` call the value is

- the object you passed (the worked example below). For a **Projection**,

- the Driver wraps the projection instance itself in the Definition —

- the projection IS the definition's value, so the field must sit

- **directly on the projection**. When the fact is computed inside a

- router case (the routed value carries it), the wiring is

- **reference-sharing**: after the single router call, point the

- projection's field at the routed value's own array —

- `this.annotations = this.value.annotations` — one array, two names;

- writes through either are visible to both (the §1 scaffold). Two

- disciplines keep it safe: a getter (`get annotations() { … }`) is

- still a method and still banned, and neither name may ever be

- **reassigned** afterward — push into the array, never replace it; a

- later `this.annotations = []` silently splits the two names onto

- different arrays with no error anywhere.

-

- ### Annotations and defaults are decided inside the per-type snippet

-

- Which serialization annotations to emit, what default value to use,

- which access modifier applies — every such decision depends on a fact

- somebody already holds, and the rule is to make the decision **where

- the fact lives**, then expose the result as a field:

-

- > The router's dispatch answers `schema.type` once. Every

- > type-dependent decision is made inside the per-type snippet that

- > dispatch constructed, and exposed as a field on the snippet

- > (`annotations`, `defaultValue`) for the consuming renderer to read.

- > Nothing outside the router ever asks `.type` again — not on a

- > schema, not on a routed value.

-

- A helper that takes a schema and asks `resolved.type === 'string'`

- after the router already dispatched is asking the already-answered

- question a second time — the structural eval's single-dispatch check

- flags exactly this, and is right to.

-

- Split every decision by where its fact lives:

-

- - **Type facts → the snippet self-declares.**

- `@JsonSerialize(using = MoneyStringSerializer::class)` derives from

- `format: 'decimal'`; `@JsonFormat(…)` from `format: 'date-time'`.

- The router's `string` case already owns those facts, and it spends

- them by CHOOSING a snippet — `BigDecimalValue`,

- `OffsetDateTimeValue`, `EnumClassValue`, or plain `StringValue` —

- each rendering exactly one Kotlin type and self-declaring the

- annotations that type implies as its protocol field

- (`annotations: KtAnnotation[]`, the same shape `KtAnnotated` gives

- class level). The line to hold: a fork that picks **different

- output types** lives in the router case (a schema-fact fork, the

- same license as the enums fork); a branch **inside** a snippet is

- only for rendering variations of the one type it renders. A

- `StringValue` whose `toString()` returns `'BigDecimal'` on one

- branch and `'String'` on another is two snippets sharing a file —

- split it; the module is named after what it renders (§6F).

- - **Defaults are the snippet's own knowledge.** A map snippet knows its

- zero value is `'emptyMap()'`; it exposes a `defaultValue` protocol

- field rather than letting the renderer inspect

- `value.type === 'object'` to decide.

- - **Position facts → the parameter renderer, no dispatch needed.**

- There are two, and they are decided in the same place: the

- `@JsonProperty("user_id")` rename (which needs `wireName` vs the

- sanitized name — facts only the object snippet has) and access

- control from `readOnly` / `writeOnly`. Access control is the one

- that reads like a type fact, because it arrives *on the schema* —

- but it belongs to the occurrence, not the type: the same `String`

- snippet may sit at a read-only property here and a writable one

- there, so a shared per-type snippet cannot carry it without being

- wrong at one of the two sites. The parameter renderer reads both per

- property and concatenates its own position annotations with the

- value's type annotations. When BOTH facts apply to one property,

- they combine into a single annotation with two named args —

- `@JsonProperty(value = "user_id", access = JsonProperty.Access.READ_ONLY)`

- — never two `@JsonProperty` annotations; the single-arg forms are

- the degenerate cases. The rule generalizes: **a fact that can

- differ between two properties of the same schema type is a position

- fact**, whatever it is declared on.

- - **Cross-type wire facts → the `in` operator.** `readOnly` /

- `writeOnly` are declared on the concrete variants, not on the

- `OasSchema` union (`union` and `unknown` have neither), so the read

- itself needs `in` — a fact read, not a dispatch:

- `'readOnly' in resolved ? resolved.readOnly : undefined`.

- - **Cross-type applicability → move the call, don't guard.** If class

- annotations don't apply to unions, let the union router case be the

- one that doesn't request them — never an internal

- `schema.type !== 'union'` guard inside the annotation helper.

-

- The mechanics, on the skeleton's shapes:

-

- ```ts fragment

- // The generator's value protocol — EVERY routed snippet carries these

- // (empty when the type implies nothing; that mild burden is the point:

- // consumers read fields, never narrow).

- export type KtValueFields = {

- annotations: KtAnnotation[]

- defaultValue?: Stringable

- // Object values only: the entries array their KtParameterList shares —

- // exposed so a union parent can reach it through the projection

- // (`inserted.definition.value.value.parameters` — the oneOf recipe).

- parameters?: KtDataClassParameter[]

- }

-

- // The router's own signature — the DEFAULT form: take the union in,

- // return the union out, intersected with the protocol. Every case

- // returns one union member, so every branch type-checks with no

- // casts and no overloads, and protocol reads are cast-free.

- export const toKtValue = (

- args: TypeSystemArgs<SchemaType>

- ): TypeSystemValue & KtValueFields => { /* switch (schema.type) … */ }

- ```

-

- The generic tightening (`<S extends SchemaType>` returning

- `TypeSystemOutput<S['type']> & KtValueFields`) exists and is almost

- never worth it. Under the doctrine, consumers read protocol fields

- and never narrow — so per-type return precision is something a

- rule-following consumer cannot even use; the one legitimate

- cross-snippet read (`parameters`) is an optional protocol field, not

- a narrowed contract field. And the generic form has a real

- implementation cost: inside the function body `S` is unresolved, so

- TypeScript cannot prove a `switch` branch's concrete snippet against

- the conditional return type — which pushes the implementation toward

- the banned `as` or an overload pair. Reach for the generic form only

- when a call site routes a *statically known* schema type and must

- read one of its CONTRACT fields without a guard; prefer widening the

- protocol with an optional field even then.

- ```ts fragment

- // Router 'string' case — the fork on schema facts CHOOSES a snippet;

- // each target renders exactly one Kotlin type and is its own module

- // (§6F: named after what it renders). Nothing inside a snippet

- // re-asks format.

- case 'string': {

- const args = { context, stringSchema: schema, destinationPath, modifiers: { required } }

- if (schema.enums) return new EnumClassValue(args)

- if (schema.format === 'decimal') return new BigDecimalValue(args)

- if (schema.format === 'date-time') return new OffsetDateTimeValue(args)

- return new StringValue(args)

- }

- ```

- ```ts fragment

- // BigDecimalValue.ts — one type; its annotations are unconditional

- // (the router fork already decided; no format branch survives here).

- export class BigDecimalValue extends KtSnippet {

- type = 'string' as const // TypeSystem contract fields (§1) — the

- format: string | undefined // 'string' OUTPUT contract, whatever renders

- // Declared EXACTLY as TypeSystemString declares it — see the

- // Nullable-generic note below; narrowing this to `string[]` is the

- // one-line change that costs a `deno check` round-trip.

- enums: string[] | (string | null)[] | undefined

- modifiers: Modifiers

- annotations: KtAnnotation[] // ← protocol: self-declared policy

- defaultValue?: Stringable

- constructor({ context, stringSchema, destinationPath, modifiers }: Args) {

- super({ context })

- this.format = stringSchema.format

- this.enums = stringSchema.enums

- this.modifiers = modifiers

- this.annotations = [

- new KtAnnotation({

- context,

- destinationPath,

- name: 'JsonSerialize',

- args: ['using = MoneyStringSerializer::class'],

- packageName: 'com.fasterxml.jackson.databind.annotation'

- })

- ]

- // Two more imports the leaf owns: the annotation's ARGS name a

- // second class (§3, one annotation, two imports), and the rendered

- // type itself is not in Kotlin's default imports.

- this.register({

- imports: {

- 'com.example.serde': ['MoneyStringSerializer'],

- 'java.math': ['BigDecimal']

- },

- destinationPath

- })

- }

- override toString(): string {

- return 'BigDecimal'

- }

- }

- // StringValue carries the same contract fields, no annotations, and

- // renders 'String'; OffsetDateTimeValue self-declares its

- // @JsonFormat and java.time import the same way.

- ```

- **The `Nullable`-generic fields keep their full union.** `enums`,

- `default`, and `example` are declared on the schema classes as

- conditionals over the class's `Nullable` parameter (`Nullable extends

- true ? (string | null)[] | undefined : string[] | undefined`). That

- parameter defaults to `boolean | undefined`, so the conditional

- distributes and never collapses — `.resolve()` does not pin it to

- `false`. At every use site the type is the widened union, and it is

- also exactly what the TypeSystem contract declares

- (`TypeSystemString.enums` IS `string[] | (string | null)[] |

- undefined`). So: copy the contract's declaration verbatim into your

- snippet field. Simplifying it to the single arm you expect compiles

- in your head and fails at `deno check` — which `skmtc bundle` will

- not catch (esbuild does not typecheck). Filter at the point of use

- instead, as `EnumClassValue` does

- (`.flatMap(entry => (entry === null ? [] : [entry]))`), not by

- narrowing the field.

- The rule is general — the trio above is not the whole list.

- **`OasObject.properties` is the same conditional shape**

- (`Record<…> | null | undefined` at use sites), so a presence guard

- must clear the `null` arm too: `Object.keys(properties)` behind a

- bare `!== undefined` check fails `deno check`; guard with

- `properties && Object.keys(properties).length` (truthiness clears

- both arms). Before assuming any schema field is plain

- `T | undefined`, check its appendix declaration for the `Nullable`

- conditional.

- ```ts fragment

- // Consumer side — the object snippet's CONSTRUCTOR makes every

- // per-parameter decision, fills the entries array, and builds the

- // KtParameterList ONCE, sharing the SAME array instance — so

- // generate-time removals (the oneOf recipe) are visible at render.

- // No `.type` anywhere: not on schemas, not on routed values.

- const entries: KtDataClassParameter[] = []

- this.parameters = entries // the KtValueFields slot a union parent may edit

- for (const [wireName, property] of Object.entries(properties ?? {})) {

- const isRequired = (required ?? []).includes(wireName)

- const value = toKtValue({ context, schema: property, destinationPath, required: isRequired })

- const inherentDefault = value.defaultValue // e.g. 'emptyMap()'

- entries.push({

- wireName, // kept for the union recipe's generate-time removal

- name: sanitizePropertyName(wireName),

- type: value,

- // Non-required is nullable UNLESS the type carries its own zero value.

- nullable: !isRequired && inherentDefault === undefined,

- annotations: [...toPositionAnnotations(wireName), ...value.annotations],

- defaultValue: isRequired ? undefined : (inherentDefault ?? 'null')

- })

- }

- this.parameterList = new KtParameterList(entries)

- ```

- ```ts fragment

- // toString() — pure interpolation of settled state. NOTHING is

- // constructed here: no snippets, no KtParameterList wrap, no Error

- // (refusals throw from the constructor). The structural eval's

- // tostring-purity check flags any `new` inside toString.

- override toString(): string {

- return `${this.parameterList}`

- }

- ```

- One more placement rule the split implies: **facts are declared in

- place — no policy module.** The `decimal` branch declares the money

- serde annotations where it branches; the `date-time` branch its

- `@JsonFormat`; the enum snippet its fallback. A central `policy.ts`

- collecting serializer class names, format patterns, and fallback

- values re-centralizes what the mapping distributes — a parallel

- dispatch table keyed by comments instead of code. A constant used

- once belongs at its use site (plain string literals are free

- everywhere; hoisting them to another module buys nothing).

- Forking *within* a router case on schema facts is the same license

- the string case's `format`/`enums` forks use — the case reads a

- schema fact and CHOOSES a snippet; it is never a second `.type`

- dispatch. The canonical instance: an `additionalProperties`-only

- object is a Kotlin `Map`, not a data class, and the split is a

- `properties`-presence check — a schema fact, not a type dispatch.

- Unlike the string forks (whose targets render different Kotlin types

- and are therefore separate snippet modules), the object fork stays

- ONE snippet for the whole case, and the stock shape dissolves the

- where-do-the-child-snippets-live question: **the TypeSystem contract

- fields themselves hold the child snippets** — `objectProperties`

- and `recordProperties` are slots the `'object'` output type demands

- anyway, each nullable, each holding the snippet that renders that

- half. No wrapper, no mirroring: the contract slot IS where the

- child snippet lives. (This shape is already worked in full in this

- skill — no need to open gen-zod's source to re-derive it.)

- ```ts fragment

- case 'object':

- return new ObjectValue({ context, objectSchema: schema, destinationPath, modifiers })

- ```

- ```ts fragment

- // The skeleton's DataClassValue, generalized (gen-zod's ZodObject

- // shape). Contract fields hold the child snippets; toString branches

- // on its OWN nullable fields — own state, never schema.type.

- export class ObjectValue extends KtSnippet {

- type = 'object' as const

- // DataClassParameters must ALSO carry a bare `properties:

- // Record<string, TypeSystemValue>` field (fill it in the same

- // per-property loop that builds `parameters`) — the router returns

- // this value as `TypeSystemValue & KtValueFields`, and the contract's

- // `TypeSystemObjectProperties` shape requires it structurally or

- // `deno check` rejects the 'object' case.

- objectProperties: DataClassParameters | null // the parameter-list snippet

- recordProperties: MapValue | null // the Map<String, V> snippet

- modifiers: Modifiers

- annotations: KtAnnotation[] = []

- defaultValue?: Stringable

- parameters: KtDataClassParameter[] | undefined // KtValueFields slot (same array the parameter-list snippet renders)

- constructor({ context, objectSchema, destinationPath, modifiers }: Args) {

- super({ context })

- this.modifiers = modifiers

- const { properties, required, additionalProperties } = objectSchema

- this.objectProperties = properties && Object.keys(properties).length

- ? new DataClassParameters({ context, properties, required, destinationPath })

- : null

- this.parameters = this.objectProperties?.parameters // reference-share upward for the oneOf recipe

- this.recordProperties = additionalProperties

- ? new MapValue({ context, schema: additionalProperties, destinationPath })

- : null

- if (this.objectProperties && this.recordProperties) {

- // zod composes this case with .and(…); Kotlin has no clean

- // data-class ∩ Map form — refuse loudly AT GENERATE (the

- // constructor), never at render: toString stays a pure read.

- throw new Error('object with both properties and additionalProperties is not mapped')

- }

- if (!this.objectProperties && this.recordProperties) this.defaultValue = 'emptyMap()'

- }

- override toString(): string {

- return `${this.objectProperties ?? this.recordProperties ?? 'Map<String, Any?>'}`

- }

- }

- ```

- ### Worked example — a serializable DTO, end to end

- import type { GenerateContextType } from '@skmtc/core'

- import {

- KtAnnotation,

- KtParameterList,

- createDataClass,

- defineAndRegister

- } from '@skmtc/lang-kotlin'

-

- type UserValueArgs = {

- context: GenerateContextType

- destinationPath: string

- }

-

- // A value class: renders ONLY what follows the head. The `annotations`

- // field is the KtAnnotated protocol — collected by KtDefinition.

- class UserValue {

- annotations: KtAnnotation[]

- parameters: KtParameterList

-

- constructor({ context, destinationPath }: UserValueArgs) {

- this.annotations = [

- new KtAnnotation({

- context,

- destinationPath,

- name: 'Serializable',

- packageName: 'kotlinx.serialization'

- })

- ]

-

- this.parameters = new KtParameterList([

- {

- name: 'userId',

- type: 'String',

- annotations: [

- new KtAnnotation({

- context,

- destinationPath,

- name: 'SerialName',

- args: ['"user_id"'],

- packageName: 'kotlinx.serialization'

- })

- ]

- },

- { name: 'name', type: 'String' },

- { name: 'email', type: 'String', nullable: true, defaultValue: 'null' }

- ])

- }

-

- toString(): string {

- return `${this.parameters}`

- }

- }

-

- export const writeUser = (context: GenerateContextType): void => {

- const destinationPath = '@/com/example/api/User.generated.kt'

-

- defineAndRegister(context, {

- identifier: createDataClass('User'),

- value: new UserValue({ context, destinationPath }),

- destinationPath

- })

- Renders — package from the path, imports self-registered by the

- annotations, annotation block from the protocol, head from the

- identifier, parens from the parameter list:

- *Which* annotations to emit (`kotlinx.serialization` vs Jackson vs

- none) is generator policy — this package renders what it is handed and

- never names a serialization library.

- ## 5. Naming & sanitization

- - **The export path IS the package.** `KtFile` derives its `package`

- directive from its own export path: the segments after `@/` are the

- package directories (`@/com/example/api/User.generated.kt` →

- `package com.example.api`; `@/models/User.generated.kt` →

- `package models`). `client.json#settings.basePath` points at the

- Gradle source root (e.g. `consumer/src/main/kotlin`), completing

- Kotlin's package-=-folder convention. So a generator's

- `toExportPath` is also its package policy — there is no separate

- package knob.

- - **Path segments must be valid package parts.** `toPackageName`

- throws when a directory segment is not a plain Kotlin identifier or

- is a hard keyword — `@/my-models/User.kt` (hyphen) or

- `@/object/User.kt` (keyword) cannot map to a package. Loud beats

- backticked package names. A root-level path (`@/Scratch.kt`) is the

- default package: legal, discouraged, renders no `package` line, and

- cannot be imported from (§3).

- - **Multi-package output** (`client.json#settings.packages`): export

- paths are forward paths under a package's `rootPath`

- (`my-sdk-core/src/main/kotlin/com/example/User.kt`), and the package

- is derived with the owning `rootPath` stripped. Each `rootPath` is

- that module's Gradle source root, exactly as `basePath` is in

- single-package mode. Cross-module imports resolve to the target

- module's real dotted package.

- - **`sanitizePropertyName(name)`** — makes a property name safe as a

- Kotlin declaration name. Plain identifier → as-is; hard keyword

- (`object`, `val`, …) or invalid name (`user name`, `1st`) →

- backticked (`` `object` ``); a name backticks cannot save (contains

- `.` `;` `:` `/` `\` `[` `]` `<` `>` a backtick or newline — illegal

- on the JVM even escaped) → throws. Returns a plain `string` (no

- quoted-property fallback exists in Kotlin).

- - **Escaping is lang-side backticks; renames are gen-side

- annotations.** The two compose, and the split decides your

- snake_case strategy: keep the wire name and backtick if needed

- (`` `object` `` still equals its wire name — no annotation), or

- rename to camelCase and annotate

- (`@SerialName("user_id") val userId`). Renaming is generator

- policy; this package only guarantees the chosen name parses.

- - **File naming**: `.kt` extension; the engine injects the

- generated-file infix (`client.json#settings.generatedSuffix`,

- default `'.generated'`) into `toExportPath` before the extension —

- `User.kt` lands as `User.generated.kt`, idempotently, exactly as

- for any language. Keep the convention — including when replacing a

- hand-written file: Kotlin resolves by **package**, not filename, so

- `Dtos.generated.kt` replaces a hand-written `Dtos.kt` without

- touching the app, and the engine-owned marker survives. An exact

- filename genuinely matters only when something outside Kotlin keys

- on it (a build script, a TS import); only then set

- `client.json#settings.generatedSuffix: ""` rather than fighting the

- suffix in the path policy. Class names come from the refName; the

- engine's cache keys on `(identifier.name, exportPath)`.

- ## 6. Kotlin-output anti-patterns

- - **Baking the head into the value** — a value `toString()` returning

- `data class User(…)` or `private class Foo`. The identifier renders

- the keyword, name, visibility, and `: TypeName`; the definition adds

- `${head}` — doubling them emits `data class User data class User(…)`.

- Return only what follows the head (§2).

- - **Adding delimiters outside the value** — wrapping a value in

- `(${value})` or `{ ${value} }` at the call site. Values own their

- delimiters: `KtParameterList` brings its parens, a body value brings

- its ` {\n…\n}`. If the output is missing parens, fix the value, not

- the caller.

- - **A manual import register next to a `KtAnnotation`** — registering

- `imports: { 'com.fasterxml.jackson.annotation': ['JsonProperty'] }`

- by hand while also constructing the annotation. Pass `packageName`

- to the annotation and delete the manual register; two statements

- drift apart (§3).

- - **Hand-rendering import or package statements in template

- literals** — they land in the file *body* (invalid Kotlin below the

- real header) and bypass sorting, dedup, and same-package

- suppression. `KtFile` owns the header; generators only register.

- - **Type-tagging imports or building barrels** — TypeScript instincts

- with no Kotlin counterpart: no type-only imports, no re-exports.

- The vocabulary omits both; don't emulate them with strings.

- - **Faking raw file content as a definition** — an identifier whose

- name never appears in the emitted code nullifies what an identifier

- is. A leading banner belongs on the register vocabulary's `custom`

- slot (§3); whole-file static content is a FILE fact, not a

- definition.

- - **Producer logic in private methods** — a `private

- toAnnotations()` on a value class or projection breaks the

- constructor + `toString()` contract exactly as a public method

- does (`skmtc-generator` §2: private helpers and accessors count).

- Annotation-building and union-membership branching belong in

- module-level free functions taking `{ context, … }` that construct

- `KtAnnotation` / snippet leaves — the leaves then self-register

- their imports.

- - **Mirroring protocol fields** — a getter

- (`get annotations() { return this.value.annotations }` — a method;

- producers are constructor + `toString()` only, and the structural

- eval's method-discipline check counts accessors), a **copy**

- (`this.annotations = [...this.value.annotations]` — a second array,

- two facts that will drift), or **reassigning an aliased name**

- (`this.annotations = []` after the alias — silently splits the two

- names onto different arrays). What IS sanctioned is

- reference-sharing: `this.annotations = this.value.annotations` in

- the constructor points the projection's protocol slot at the routed

- value's own array — one array, two names — and is the canonical

- wiring (§4); after that line, push, never replace.

- - **Re-deriving schema facts outside the router** — an annotation or

- default-value helper that takes a schema and asks

- `resolved.type === 'string'` (or narrows a routed value with

- `value.type === 'object'`) after the router already dispatched. The

- mapping extracted that fact once; policy consumes it as a protocol

- field (`annotations` / `defaultValue` — §4) or an `in` fact-read,

- never by a second dispatch. The single-dispatch check flags every

- such site.

- - **Running a formatter over the output** — render is unformatted by

- design; the consumer's ktfmt/ktlint formats. Trailing commas,

- line-wrapping, and indentation niceties are their territory.

- - **Mismatched `lang-kotlin` pins across the stack** — two copies of

- the package (e.g. a local generator pinning a different version

- than a JSR peer) break cross-copy `instanceof`: `KtFile` /

- `KtIdentifier` checks fail in ways that look like engine bugs. Every

- package in one build must pin the SAME `@skmtc/lang-kotlin` version.

- - **Export paths that cannot be packages** — `@/my-models/…`,

- `@/models/v1.2/…`, a hard-keyword segment. `toPackageName` throws at

- render, far from the `toExportPath` that caused it; fix the path

- policy (§5).

- ## 7. Boundary with other skills

- - **`skmtc-generator`** — everything engine-side: Projections vs

- Snippets, `transform` returning void, `insertModel` /

- `insertOperation` / `findDefinition`, the constructor/`toString()`

- contract, enrichments, variants, cross-generator coordination. If

- the question is "how do generators work", it's there; if it's "what

- does the emitted Kotlin look like", it's here.

- - **`skmtc-cli`** — install/bundle/generate commands, registering a

- local generator in a workspace.

- - **`skmtc-debug`** — broken output, verify-first stance.

- - **`skmtc-lang-typescript`** — the TypeScript counterpart and the

- template this skill follows; useful contrastively (type-only

- imports, re-exports, and quoted-property fallbacks exist THERE, not

- here).

- ### Status note

- Current model: the **head+value rewrite** — the identifier renders its

- declaration head, the value renders everything after it, and the

- former `KtSupertyped` / `KtConstructed` value protocols and the

- `verbatim` identifier kind are gone (historical: supertype clauses and

- braced bodies are now written inline; primary constructors compose

- `KtPrimaryConstructor`; raw file content goes through the `custom`

- slot). `KtFile.header` / `fileHeader` were superseded by `custom`.

- The package lives at `deno/lang-kotlin` (see its `deno.json` for the

- current version; released through the workspace cascade against the

- pinned `@skmtc/core`). Proving generators: the `gen-kotlin*` family —

- being rewritten onto this model; the migration log is

- `notes/lang-v2/02-lang-kotlin-changes-for-generator-rewrite.md`.