The Kotlin layer (@skmtc/lang-kotlin)

Read skmtc-generator first.

Drift warning. The API of record is the workspace skmtc/deno/lang-kotlin and its tests. The shipped gen-kotlin-* generators predate the 0.9.11 flattening: they call new KtAnnotation('Name', [args]) positionally and import isKtAnnotated/isKtSupertyped (no longer exported; supertype clauses now render inline in the value). Clone their structure only; take call shapes from THIS skill's example (§8), which is pinned byte-for-byte against the engine by lang-kotlin/src/skill-example.test.ts.

1. Declaring the language

Same pattern as TypeScript — the import graph declares it. Two factories: toKtModelProjectionBase, toKtOasOperationProjectionBase; snippets extend KtSnippet.

export const KtModelBase = toKtModelProjectionBase<EnrichmentSchema>({
  id: denoJson.name,
  toEnrichmentSchema,
  toIdentifierName({ refName, enrichments }) {
    return enrichments?.subject?.name ?? capitalize(camelCase(refName))
  },
  // Kotlin's identifier KIND depends on schema shape → may read context
  // (runs only on cache-miss; the NAME stays pure):
  toIdentifierType(refName, context) {
    return { type: toShape(context, peekSchema(context, refName)) }
  },
  toExportPath({ refName, enrichments }) {
    const name = enrichments?.subject?.name ?? capitalize(camelCase(refName))
    return `@/${enrichments.generator.basePackage.replaceAll('.', '/')}/${name}.generated.kt`
  }
})

The export path's directory segments ARE the Kotlin package (§4). Make basePackage a required generator-scope enrichment with no default; validate segments with isKtIdentifierName + ktHardKeywords. Put the shape dispatch (object+props → data-class; string+enums → enum-class; qualifying discriminated union → sealed-interface; else typealias) in ONE deterministic function read by both toIdentifierType and the constructor, so kind and value can't disagree.

2. Register shapes — Kotlin differences

Same three shapes as TS (projection own-file / registerInto / snippet with required destinationPath), plus defineAndRegister (no cache check; no noExport — visibility is the identifier's fact: pass exported: false to the factory). Compile-time differences: no reExports field (Kotlin has none) and no type tag on imports (no type-only imports). custom renders above the package directive.

3. Identifier kinds

Kotlin output has seven entity kinds (KtEntityType): class, data-class, enum-class, interface, sealed-interface, typealias, val — factories createClass, createDataClass, createEnumClass, createInterface, createSealedInterface, createTypeAlias, createValue (only createValue takes typeName; exported: false renders private ). Deferred kinds (object, fun, var) make toKtEntityType throw — deliberately loud. Kind does NOT affect import form. The engine's type is an opaque string: isKtEntityType narrows it to the vocabulary above, and isKtIdentifier narrows a neutral IdentifierBase back to KtIdentifier.

4. Emitted-import rules

Packages from paths: @/com/example/api/User.generated.kt → package com.example.api. Segments are validated, never sanitized — a keyword or invalid segment throws (fix the path policy).
One import pkg.Name per symbol (no brace grouping), as aliases, rendered sorted (determinism, not style).
Same-package suppression is central: register imports unconditionally; KtFile drops same-package ones at render.
Importing from the default package throws (root-level artifact referenced from a packaged one = path-policy bug).

5. Render model: head + value

Assignment kinds (typealias, val): <head> = <value>. Declaration kinds: <head><value> — the value renders everything after the name: parameter list (parens included), inline : Parent clauses, { … } bodies; an empty value yields the bodyless idiom (sealed interface Animal).

Two things ride on value-carried protocols (the neutral Lang signature has no slot for them): KtAnnotated (annotations: KtAnnotation[], strict — string look-alikes are silently dropped) and KtDocumented (description, guard isKtDocumented, rendered as KDoc above the annotations). The mirroring gotcha: the Driver wraps the PROJECTION as the definition's value, so mirror both onto the projection — canon is reference assignment in the constructor (this.annotations = this.value.annotations — one array, two names; never copy) — or class-level annotations and KDoc silently vanish.

6. Composition classes (current API)

KtParameterList(parameters) — parens included; each { name, type: Stringable, nullable?, defaultValue?, annotations?, visibility? } renders as an indented val, annotations one per line.
KtPrimaryConstructor({ parameters, modifiers? }) — modifiers force the explicit constructor keyword.
KtFunctionSignature({ name, parameters, returnType?, annotations?, body? }) — abstract by default, expression body only.
KtAnnotation({ context, name, args?, target?, packageName?, destinationPath }) — a registering leaf: with packageName it registers its own import (register unconditionally; suppression handles same-package). args are pre-quoted (['"user_id"'], ['Foo::class']). target is the use-site target (KtAnnotationTarget: field/get/set/…) rendered as @field:JsonAnySetter — the imported symbol stays the bare name. Needed on a constructor val, which is parameter/property/field/ getter at once: Jackson's catch-all pair is @field:JsonAnySetter + @get:JsonAnyGetter, and without targets both annotations land on the parameter, where Jackson never looks. (Shipped in lang-kotlin 0.10.0, 2026-08-04 — pre-target versions cannot express use-site targets at all.)
withDescription(value, { description }) — KDoc.

7. Sanitization and @SerialName

sanitizePropertyName(name): plain → unchanged; hard keyword or invalid → backticked; JVM-unescapable characters → throws ("rename + @SerialName"). Renames are NOT its job — serialization annotations handle wire-name mismatches, and the two compose: decide the annotation by comparing the unescaped chosen name with the wire key (`object` needs no @SerialName; user_id→userId does). Only the 28 hard keywords escape; soft/modifier keywords (value, data, sealed) are legal identifiers. Canonical pairing: sanitizePropertyName(camelCase(key)).

8. Worked example — kotlinx data class (current API, engine-pinned)

Per-property loop inside the data-class value snippet:

const propertyName = sanitizePropertyName(camelCase(key))
const annotations: KtAnnotation[] = []
if (propertyName.replaceAll('`', '') !== key) {
  annotations.push(new KtAnnotation({
    context, destinationPath,
    name: 'SerialName', packageName: 'kotlinx.serialization', args: [`"${key}"`]
  }))
}
parameters.push({
  name: propertyName,
  type: value,                     // the SNIPPET — never `${value}`
  defaultValue: isRequired ? undefined : 'null',
  annotations
})
// this.parameterList = new KtParameterList(parameters)
// class-level: this.annotations = [new KtAnnotation({ context,
//   destinationPath, name: 'Serializable', packageName: 'kotlinx.serialization' })]
// projection mirrors by REFERENCE: this.annotations = this.value.annotations

Renders (verified byte-for-byte through the engine):

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
)

The type expression is the single owner of ?; the parameter layer only adds = null. Passing `${value}` instead of the snippet strands its registered imports and synthesized siblings — the file breaks far from the cause. Serialization flavor is confined to the value files (data class / enum entries / sealed interface): a Jackson/Moshi sibling generator swaps annotation construction there only.

8b. Normalized models — KNOWN ENGINE GAP (verified 2026-08-03)

The head+value model means a Kotlin value renders differently in TYPE position (Map<String, Any?>) and DECLARATION position (a parameter list). Core's generic insertNormalizedModel glues the identifier head to the value's type-position toString() — which for an inline OBJECT schema renders invalid Kotlin: data class XMap<String, Any?>. The engine gap is real, but the SOLUTION does not wait for it — every mature Kotlin generator solves inline objects the same way:

Named $ref schemas are unaffected — insertModel and the ref path work correctly.
An inline NON-object schema normalizes fine as a typealias-shaped value.
An inline object is SYNTHESIZED as a named sibling declaration and referenced by name — the retired gen-kotlin-kotlinx pattern (KtObjectValue, skmtc-generators history at 2c24a65) rebuilt WITHOUT its naming-hint threading: the name derives from the schema's own stackTrail (toSynthesizedName.ts in gen-kotlin-jackson — anchor on the components/paths landmark frames, never absolute indices; classification is POSITIONAL: properties consumes the following frame as a literal key, so a property named properties/schema/items can never be mistaken for trail structure), so every construction path — including peers arriving through insertNormalizedModel — lands on the same name with NO parameter added to the router contract. Names are NOT collision-free: claim via the document-wide registry (claimSynthesizedName, gen-kotlin-jackson synthesizedNames.ts) BEFORE declaring — it throws per-item when the name collides with a component-derived class name (Kotlin's redeclaration scope is the PACKAGE, not the file) or with a different position's claim (camelCase-convergent keys), and returns reuse for a same-position re-walk. On 'declare', defineAndRegister the sibling and render only the NAME. Type position then always holds a name or a map — never property structure. This is also how OpenAPI Generator solves it (inline schemas hoisted to named components before generation). Widening a known shape to Map<String, Any?> is capitulation, not a solution — it discards the type the schema gave you. Inline string enums synthesize the same way (enum class sibling).
Never fabricate a refName or drive the peer's identity statics to force a declaration into existence — that is the two-doors rule (skmtc-generator §4), and the result couples you to the peer's private snippet shape.

8c. Discriminated unions — sealed interfaces (shipped 2026-08-04)

Kotlin has no union type; a QUALIFYING discriminated union becomes a sealed interface (gen-kotlin-jackson is the worked example; ancestry: the retired kotlinx machinery at skmtc-generators 2c24a65, stale call shapes). Predicate (shape.ts isSealedUnion, part of the shape dispatch): discriminated, ≥2 members, every member a $ref to an object-with-properties, and every member keeps ≥1 parameter AFTER discriminator omission. Everything else renders the honest wire type (JsonNode for Jackson), never Any.

The inversion scan. OpenAPI points parent → member; Kotlin declares member → parent (data class Dog(...) : Pet). Memoization makes build order arbitrary, so membership must be known BEFORE any construction: one document-wide scan over components.schemas, memoized per document via WeakMap, mapping member refName → claims. Claims store the parent's real RefName; the consumer derives the display name via context.toModelContentSettings — never a copy of the naming policy, never a fabricated refName.
Parent side: an empty-body value (toString() returns '' → the bodyless idiom) carrying @JsonTypeInfo(use = NAME, include = PROPERTY, property = "<discriminator>") + @JsonSubTypes(Type(value = Dog::class, name = "dog"), …) via the KtAnnotated protocol — mirror annotations AND description on the projection by reference. Each subtype entry holds the walked member ref SNIPPET, so member models build and imports stitch through the normal chain. Tags: discriminator.mapping key pointing at the member, else the member's refName (the OpenAPI default).
Member side: inline : Pet supertype clause rendered by the parameter-list value (after the parens), and the discriminator property OMITTED — filtered BEFORE the property walk, or its enum schema synthesizes a spurious sibling. Same package by the export-path policy satisfies Kotlin's sealed same-package rule.
Jackson vs kotlinx flavor: tags are parent-side (@JsonSubTypes), so members carry no tag annotation and one member may hold different tags under different parents (the kotlinx one-@SerialName-per-class conflict rule does not apply).
Runtime gotcha (probed): a raw writeValueAsString(list) erases the element type and silently DROPS the tags; concrete roots, writerFor(type), and full-generic types all write them — Spring MVC uses the typed path, so real consumers are fine. Test round-trips with a typed writer.
allOf-composed members (the spec's canonical idiom: shared fields on a base, members compose via allOf) qualify WITHOUT special handling — core resolves allOf at parse time (mergeIntersection), so the member peeks as a flat object and the base's fields flatten into each data class (verified through the pipeline 2026-08-04). Flattening is the right Kotlin target: the sealed interface is the polymorphism seam, not class inheritance.
Inline unions (stage 2, shipped): a qualifying union ANYWHERE — component property, operation body/response/header/parameter — synthesizes its sealed parent under its stackTrail name (combinator frames oneOf/anyOf/allOf are structural and elided; a parameters/<index> position resolves to the parameter NAME via a WeakMap document scan — the trail itself cannot carry names, it doubles as a JSON Pointer where parameters is an array) into the MODELS package (toModelExportPath — ONE placement policy for EVERY synthesized declaration; caller's-file placement breaks 'reuse'-across-files for cross-package peers). The scan deep-walks components AND operations AND webhooks (headers and the content alternative included); synthesized claims carry the union NODE so ensureSealedParent lets WHOEVER needs the name first declare it via the claim registry. Derivability is ONE shared non-throwing probe (toSynthesizedNameOrNull) across scan/render/members — underivable roots degrade consistently to pre-synthesis behavior; the object/enum sites deliberately keep the THROWING derivation (no honest fallback exists for structure). One member may implement several sealed parents (parent-side tags).
Not yet built: undiscriminated unions (stage 3 — enrichment-asserted hints / Jackson Id.DEDUCTION) and the INVERTED swagger-style pattern (discriminator on the base, no oneOf, membership implied by allOf back-references — no union node exists, so no sealed interface).

9. Kotlin pitfalls

Symptom	Fix
`@Serializable`/KDoc missing	Mirror `annotations`/`description` getters on the projection
Annotation silently dropped	Real `KtAnnotation` instances, not strings
`segment 'x' is not a valid package name part`	Fix the export-path policy — packages validate, never sanitize
Import mid-file / duplicated	`register` / annotation `packageName`, never templates
`String??`	Type expression owns the single `?`
`Unknown Kotlin entity type`	Use the seven Kotlin factories, not TS kinds
Empty `data class` throws	Shape dispatch must route empty objects to `typealias`
TDZ crash at module load	Break base↔router↔projection cycles with a leaf module (`peekSchema` pattern)
Nondeterministic output	No module state; config via enrichments; memoize document scans in `WeakMap`
`data class X` glued to `Map<String, Any?>`	The normalized-insert type/declaration gap — §8b, don't hack around it
Union renders `Any`/`JsonNode` where a sealed type was expected	Qualifying predicate failed — check discriminator presence, all-ref members, per-member surviving parameters (§8c)
Member missing `: Parent` / spurious discriminator enum sibling	Membership scan not consulted before construction, or omission applied after the property walk (§8c)
Sealed round-trip loses the wire tag at runtime	Jackson root-list type erasure — serialize via a typed writer; generated code is correct (§8c)

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

skmtc-lang-kotlin

Files2

SKILL.mddeno/docs/skills/skmtc-lang-kotlin/SKILL.md