skmtc-lang-kotlin

name	skmtc-lang-kotlin
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

// 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({
  id: denoJson.name,
  // 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
})

// 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}`
  }
}

// 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):

// 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:

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):

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:

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 KtImports at the boundary:

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:

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 Stringables; 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:

// 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 })

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):

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:

  // 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:

  // 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
    }
  }
  

  // 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:

// 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):

case 'string':
  return schema.enums
    ? new EnumClassValue({ context, stringSchema: schema, destinationPath, modifiers })
    : new StringValue({ context, stringSchema: schema, destinationPath, modifiers })

// 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:

// 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.

// 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)
}

// 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.

// 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)

// 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.)

case 'object':
  return new ObjectValue({ context, objectSchema: schema, destinationPath, modifiers })

// 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:

package com.example.api

import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

@Serializable
data class User(
    @SerialName("user_id")
    val userId: String,
    val name: String,
    val email: String? = null
)

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.

Appendix — generated API reference

The full deno doc surface for the packages this skill covers lives in appendix.md, in this skill's directory — generated from framework source at 71ef53bc, signatures and field docs only. It is authoritative: when the prose above does not carry the exact constructor or field shape you need, Read (or grep) appendix.md instead of diving into package source. Do not guess signatures. For a symbol not listed there, deno doc <file> <Symbol> against the framework source beats grepping it.