Axiomatic Reasoning for LLMs

Implementation Plan on Kotlin

1. Core Principles to Kotlin Mapping

Principle	Kotlin Implementation	Tooling
Intent–Structure–Implementation Separation	Interface (specification) + data class (data) + concrete class (implementation)	Kotlin compiler
Generative Conformance	Code generation from OpenAPI / JSON Schema / annotations	KSP + KotlinPoet, OpenAPI Generator
Skeleton–Tissue Architecture	`public` interfaces (skeleton) + `internal` implementations (tissue)	Access modifiers, sealed classes
Recursive Refinement with Fixed Premises	Module boundaries + Git tags + incremental builds	Gradle, KSP incremental processing
Validation Gates	Compiler checks + static analysis + architecture tests	Kotlin compiler, Detekt, ArchUnit

2. Structural Specification Formats

Scope	Format	Generation Target
API boundaries (REST)	OpenAPI 3.0+ YAML	Ktor/Spring server stubs, client libraries
Data models	JSON Schema or Kotlin data classes	POJOs / data classes, JSON schema
Service contracts	gRPC + Protocol Buffers	Kotlin gRPC stubs (grpc-kt)
Domain constraints	Custom annotations + KSP	Validation code, state machines

Selection rule: OpenAPI for external APIs, JSON Schema for shared data, gRPC for internal services, custom annotations for domain‑specific rules.

3. Code Generation Pipeline

3.1 KSP + KotlinPoet (Core Infrastructure)

KSP processes annotations at compile time. KotlinPoet generates .kt files programmatically.

// Custom processor skeleton
class DeepCodingProcessor : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> {
        val symbols = resolver.getSymbolsWithAnnotation("GenerateTissue")
        symbols.forEach { symbol ->
            val fileSpec = buildTissueClass(symbol)
            fileSpec.writeTo(codeGenerator)
        }
        return emptyList()
    }
}

3.2 OpenAPI Generator for API Layer

Gradle plugin configuration:

openApiGenerate {
    generatorName.set("ktor")   // or "spring"
    inputSpec.set("$projectDir/src/main/resources/api.yaml")
    outputDir.set("$buildDir/generated")
    apiPackage.set("com.example.api")
    modelPackage.set("com.example.model")
}

3.3 kotlinx-schema (Experimental)

Generates JSON Schema from @Schema annotated data classes at compile time.

@Schema
data class Product(
    val id: Long,
    val name: String,
    val price: Double
)
// Schema accessible via Product::class.jsonSchemaString

4. Skeleton–Tissue Separation in Kotlin

4.1 Skeleton Layer (Manual, Immutable, `public`)

Interfaces define contracts.
Sealed interfaces define closed state spaces.
Extension functions provide template methods.

// skeleton/ServiceSkeleton.kt
interface ServiceSkeleton {
    fun execute(input: Input): Output
}

fun ServiceSkeleton.executeWithLogging(input: Input): Output {
    println("Executing: $input")
    return execute(input)
}

sealed interface ResultState
data class Success(val data: Output) : ResultState
data class Failure(val error: String) : ResultState

4.2 Tissue Layer (Generated, `internal`)

Concrete implementations reside in internal visibility.
Generated code placed in src/main/kotlin/tissue/generated/.
Manual extensions use separate files with same package.

// tissue/generated/ServiceTissue.kt (generated by KSP)
internal class ServiceTissue : ServiceSkeleton {
    override fun execute(input: Input): Output {
        // Generated business logic
        return Output("Processed: ${input.value}")
    }
}

4.3 Delegation Pattern with `by`

class ServiceCoordinator(
    private val tissue: ServiceTissue
) : ServiceSkeleton by tissue

5. Validation Gates (Multi‑Layer)

Layer	Tool	Enforced Property
Compiler	Kotlin compiler	Null safety, type safety, `when` exhaustiveness for sealed classes
Access control	`internal` + Gradle modules	Tissue implementations not visible outside module
Static analysis	Detekt custom rules	Package naming, dependency direction (tissue → skeleton only)
Architecture tests	ArchUnit	Layer dependencies, no circular dependencies
Generation-time	KSP processor	Structural specification conformance

Detekt custom rule example (tissue not depending on other tissue):

class TissueDependencyRule : Rule() {
    override fun visitClass(klass: KtClass) {
        // Check import statements and supertypes
    }
}

ArchUnit test:

@Test
fun `tissue depends only on skeleton`() {
    val rule = noClasses()
        .that().resideInPackage("..tissue..")
        .should().dependOnClassesThat()
            .resideInPackage("..tissue..")
    rule.check(importedClasses)
}

Phase N complete
    │
    ├── Git tag: phase-N-complete
    ├── Save structural specification snapshot
    │
    ▼
Modify specification (OpenAPI YAML, annotations, .proto)
    │
    ├── KSP incremental processing detects changes
    ├── Regenerate affected tissue code only
    │
    ▼
Validation gates (compiler → Detekt → ArchUnit → tests)
    │
    ├── On failure: reject change, rollback to tag
    ├── On success: commit new specification and generated code
    │
    ▼
Phase N+1 complete
    │
    └── Git tag: phase-N+1-complete

Gradle incremental build configuration:

tasks.named("compileKotlin") {
    dependsOn("generateCode")
}
tasks.named("generateCode") {
    inputs.dir("src/main/resources/specification")
    outputs.dir("$buildDir/generated")
}

7. Platform‑Specific Adaptations

7.1 Ktor Server

OpenAPI Generator produces interface stubs.
Manual implementations extend generated interfaces.
Ktor’s openapi plugin can generate OpenAPI from code (reverse direction).

7.2 Android (Clean Architecture)

Clean Architecture Layer	Deep Coding Layer	Implementation
Domain (interfaces)	Skeleton	`public` interfaces, `sealed` states
Data (repositories)	Tissue	`internal` implementations, KSP generated
Presentation	Framework layer	Deep Coding not applied

7.3 Kotlin Multiplatform (KMP)

Common module: skeleton interfaces and data models.
Platform modules: tissue implementations generated per platform.
expect/actual declarations align with skeleton‑tissue separation.

8. Implementation Phases

Phase	Scope	Deliverable	Duration
0	Infrastructure	Gradle setup, KSP module, KotlinPoet dependency	1 week
1	Skeleton design	Core interfaces, sealed state definitions	1-2 weeks
2	Structural specification	OpenAPI YAML, custom annotations, JSON Schema	1 week
3	Generation pipeline	KSP processors, OpenAPI Generator integration	2 weeks
4	Validation gates	Detekt custom rules, ArchUnit tests, CI integration	1 week
5	Pilot module	Apply to one module, measure build time and conformance	1-2 weeks

9. Constraints and Mitigations

Constraint	Mitigation
KSP learning curve	Start with small annotation processors; use existing examples
kotlinx-schema experimental status	Use OpenAPI Generator for production; monitor kotlinx-schema maturity
Existing Java codebase	Apply Deep Coding to new Kotlin modules only; use facade pattern for legacy integration
Build time in large projects	Incremental KSP processing + Gradle build cache
Reflection‑heavy frameworks (Spring, Hibernate)	Limit Deep Coding to contract and DTO layers; use traditional implementation for persistence

10. Summary

Kotlin provides all necessary language features and tooling for a specification‑driven, AI‑assisted development workflow:

Structural separation via interfaces, data classes, and sealed types
Generative conformance via KSP, KotlinPoet, and OpenAPI Generator
Skeleton–tissue separation via public/internal visibility and module boundaries
Validation gates via compiler checks, Detekt, and ArchUnit
Recursive refinement via incremental builds and Git tagging

The plan is ready for production use in Ktor server applications, Android projects, and Kotlin Multiplatform environments. New modules can adopt the full pipeline; existing codebases can integrate gradually.

This site is open source. Improve this page.