GUIDE — Kotlin under the Discipline, v0.1

0. Language baseline

• 04Kotlin 2.1+ (K2 compiler), target latest stable. Gradle with version catalogs + convention plugins — the ecosystem reality (KMP is Gradle-only); Maven legal for pure-JVM targets. Dependency locking on (A2).
• allWarningsAsErrors = true. explicitApi() is MUST for cell modules — explicit visibility and return types on every public declaration: surface honesty as a compiler flag, not a review note.
• Surface ratchet: kotlinx-binary-compatibility-validator (Apache-2.0) — committed .api dumps, diffed in PRs; an unexplained surface change is a finding before it is an API break.
• Lint gate: detekt (Apache-2.0) — and its baseline file is a native brownfield ratchet (BROWNFIELD §B1 shipped inside the tool: existing findings frozen, new ones fail, the file only shrinks). Formatting via one pinned formatter (ktlint/ktfmt) — zero discipline budget.
• Suppression policy (xfail-strict posture): @Suppress only with the narrowest scope, the specific check name, and a // reason; a conform sweep re-runs named checks against suppressed elements and fails stale entries.
• Null discipline: !! is banned in cells (the assert-shaped escape hatch); lateinit is banned in cells (two-phase-init smell — constructor injection removes the need); platform types (T!) are quarantined: every value arriving from Java interop is pinned to explicit nullability at the boundary before it travels. val is the default; var is justified.
• Tests: kotlin-test in common code; JUnit 5 on JVM (EPL-2.0 flag inherited from the Java trunk); property testing via kotest-property (Apache-2.0) — a license upgrade over Java's EPL-flagged jqwik. MockK and Mockito are banned in cell tests — same rule, same reason as every sibling guide: capability injection makes module-graph mocking unnecessary.

1. Cells

05A cell is a Gradle module (in KMP, its commonMain source set — Part III makes that physics). explicitApi + the .api dump define its surface; promotion/extraction on the usual triggers.

• 06Import-is-execution, Kotlin edition: object and companion object initialize lazily on first touch; top-level property initializers run at file-class init. Side effects there are banned in cells. object is legal only as a pure namespace (stateless vals and functions); an object holding mutable state or doing registration is the singleton the trunk forbids, now with keyword support.
• Capabilities are injected, including the ones Kotlin is famous for forgetting: CoroutineDispatcher/CoroutineContext is an injected capability — hardcoded Dispatchers.IO/Dispatchers.Main in a cell is a finding (and the reason cell tests never need a main-dispatcher rule); Clock (kotlinx-datetime) injected; filesystem/network/env never ambient.
• Messages crossing seams are data classes of vals (or data objects); collections crossing seams are read-only types honestly backed.

07Cell manifest (annotation carrier, §5):

@SpecImplements("spec://org.vibevm.core/vibevm/modules/vibe-resolver/PROP-003#solver-upgrade", r = 2)
@Cell(seam = "DepSolver", variant = "sat", replaces = "naive", flag = "solver")
class SatDepSolver(
    private val provider: DepProvider,
    private val clock: Clock,
    private val dispatcher: CoroutineDispatcher,
) : DepSolver { /* ... */ }

2. Seams

• 09A seam is an interface in the seams module; closed sets are sealed. Conformance is nominal — no assertions needed.
• suspend functions are the async seam form. This is a declared divergence from the Java trunk (which prescribes blocking seams on virtual threads): each trunk follows its platform's structured-concurrency culture, and at a mixed JVM boundary a one-function bridge (runBlocking/Dispatchers adapter) converts — the divergence is owned, not hidden.
• Interface default implementations follow the trunk-wide rule: trivial combinators only, never business flow (R-021).
• Flow at seams is cold; hot state (StateFlow/SharedFlow) is owned by a named state holder with an explicit lifetime, exposed read-only.

3. Registry and flags

// registry module — the only flag reader and the only module depending on cells.
fun depSolver(cfg: AppConfig, p: DepProvider, clock: Clock, io: CoroutineDispatcher): DepSolver =
    when (cfg.solver) {                       // provenance: default | env | cli | lockfile
        Solver.SAT   -> SatDepSolver(p, clock, io)
        Solver.NAIVE -> NaiveDepSolver(p)
    }

• 11Tiers: assembly tier = which modules (and, in KMP, which targets) are built — "is the code in the artifact"; runtime tier = a config data class bound once in main. expect/actual never encodes product variants — it is platform adaptation only; a product flag wearing expect clothing is a finding.
• No ServiceLoader-style discovery, no reflection wiring, no DI container in the trunk; Parts II–III legalize containers strictly as composition-root machinery.

4. Errors as contract

12Kotlin removed Java's checked exceptions — deliberately — and put nothing in the signature where they stood: exceptions here are unchecked and undeclared, the most vanished failure surface in the set. The Discipline restores it the same way as everywhere:

• 13Seam-owned sealed results, consumed by exhaustive when as an expression, with no else branch — a new permitted subtype must break every consumer's build (the default-arm ban, fourth appearance):

sealed interface SolveResult {
    data class Ok(val resolution: Resolution) : SolveResult
    data class Err(val error: SolveError) : SolveResult
}
data class SolveError(val code: Code, val spec: String, val cause: Throwable? = null) {
    enum class Code { CYCLE, UNSATISFIABLE }
}

15spec carries the violated REQ URI (PROP-014 §2.6). kotlin.Result<T> is not a seam type — its error channel is pinned to Throwable, which is an implementation genus, not a domain contract. Arrow's Either/Raise (Apache-2.0) is parked exactly as Effect-TS was: an optional profile for FP-shaped carriers, not the trunk binding.

• 16Exceptions = invariant violations (panic analog). Boundary adapters translate library exceptions into seam errors.
• Cancellation sanctity — the №1 coroutine footgun: a broad catch (e: Exception) silently eats CancellationException and breaks structured cancellation; every broad catch MUST rethrow it (detekt rule + conform check).
• Structured concurrency is native — keep it that way: GlobalScope is banned (the language's one escape hatch from its own best idea); runBlocking only at main/test edges; scopes are owned (coroutineScope/supervisorScope or an injected scope with a named lifetime); a coroutine that outlives its cell is a leak by definition.

5. specmark carrier

17The same specmark annotations as Java, defined once in commonMain and visible to every target: AnnotationRetention.BINARY (in the artifact for analysis, invisible to runtime reflection), @Repeatable, @MustBeDocumented — edges render in Dokka, so the carrier doubles as the doc surface. File-level scope uses Kotlin's native syntax — @file:SpecScope("<uri>", r = N) — because the file, not the package, is Kotlin's organizational unit (no package-info needed). ≤3 edges per item or split.

6. Naming (R-020/R-021 bindings)

• 18Computed {Variant}{Seam} → SatDepSolver; linted against the manifest.
• The Kotlin theater list — placement, not amputation: the language's DSL powers (lambda-with-receiver builders, infix, operator overloading) are banned in domain cells and legal where they shine — boundaries, configuration, test fixtures (Gradle and Ktor routing are the canonical homes). Also banned in cells: operator overloading beyond value semantics; delegated properties with side effects (by lazy of a pure value is fine; observable/vetoable is hidden control flow); extension functions on foreign types sprayed outside the owning cell; kotlin-reflect; companion-object registries; !!/lateinit (§0).

7. Replacement protocol (R-040 binding)

19Differential oracle via kotest-property driving both cells through the seam (@SpecVerifies-tagged), divergences documented. Goldens follow the promotion protocol. On JVM the Java trunk's strict @KnownFailing JUnit extension carries over as the in-source twin of tests-baseline.json; in common tests, the baseline registry carries the weight alone (Go's situation) — stated, not hidden.

8. Risk table — trunk

9. Doc layer

21KDoc + Dokka on every public declaration (explicitApi already forces you to notice them): behavior, seam error codes with REQ URIs, nullability beyond the types, coroutine context expectations (which dispatcher, cancellation behavior), Flow temperature. @MustBeDocumented specmark edges render alongside. Spec stays thin.