Kotlin SDK API Proposal

.gitignore

@@ -0,0 +1,4 @@
+.idea/
+.claude/
+*.iml
+CLAUDE.md

kotlin/README.md

@@ -0,0 +1,134 @@
+# Kotlin SDK API Proposal
+
+This document describes the public API and developer experience for the Temporal Kotlin SDK.
+
+## Overview
+
+The Kotlin SDK provides an idiomatic Kotlin experience for building Temporal workflows using coroutines and suspend functions.
+
+**Key Features:**
+
+* Coroutine-based workflows with `suspend fun`
+* Full interoperability with Java SDK
+* Kotlin Duration support (`30.seconds`)
+* DSL builders for configuration
+* Null safety (no `Optional<T>`)
+
+**Requirements:**
+
+* Minimum Kotlin version: 1.8.x
+* Coroutines library: kotlinx-coroutines-core 1.7.x+
+
+## Design Principle
+
+**Use idiomatic Kotlin language patterns wherever possible instead of custom APIs.**
+
+The Kotlin SDK should feel natural to Kotlin developers by leveraging standard `kotlinx.coroutines` primitives. Custom APIs should only be introduced when Temporal-specific semantics cannot be achieved through standard patterns.
+
+| Pattern | Standard Kotlin | Temporal Integration |
+|---------|-----------------|----------------------|
+| Parallel execution | `coroutineScope { async { ... } }` | Works via deterministic dispatcher |
+| Await multiple | `awaitAll(d1, d2)` | Standard kotlinx.coroutines |
+| Sleep/delay | `delay(duration)` | Intercepted via `Delay` interface |
+| Deferred results | `Deferred<T>` | Standard + `Promise<T>.toDeferred()` |
+
+This approach provides:
+- **Familiar patterns**: Kotlin developers use patterns they already know
+- **IDE support**: Full autocomplete and documentation for standard APIs
+- **Ecosystem compatibility**: Works with existing coroutine libraries and utilities
+- **Smaller API surface**: Less custom code to learn and maintain
+
+## Documentation Structure
+
+### Core Concepts
+
+- **[Kotlin Idioms](./kotlin-idioms.md)** - Duration, null safety, property syntax for queries
+- **[Configuration](./configuration/README.md)** - KOptions classes, data conversion, interceptors
+
+### Building Blocks
+
+- **[Workflows](./workflows/README.md)** - Defining and implementing workflows
+  - [Definition](./workflows/definition.md) - Interfaces, suspend methods, Java interop
+  - [Signals, Queries & Updates](./workflows/signals-queries.md) - Communication patterns
+  - [Child Workflows](./workflows/child-workflows.md) - Orchestrating child workflows
+  - [Timers & Parallel Execution](./workflows/timers-parallel.md) - Delays, async patterns
+  - [Cancellation](./workflows/cancellation.md) - Handling cancellation, cleanup
+  - [Continue-As-New](./workflows/continue-as-new.md) - Long-running workflow patterns
+
+- **[Activities](./activities/README.md)** - Defining and implementing activities
+  - [Definition](./activities/definition.md) - Interfaces, typed/string-based execution
+  - [Implementation](./activities/implementation.md) - Suspend activities, heartbeating
+  - [Local Activities](./activities/local-activities.md) - Short-lived local activities
+
+### Infrastructure
+
+- **[Client](./client/README.md)** - Interacting with workflows
+  - [Workflow Client](./client/workflow-client.md) - KClient, starting workflows
+  - [Workflow Handles](./client/workflow-handle.md) - Signals, queries, results
+  - [Advanced Operations](./client/advanced.md) - SignalWithStart, UpdateWithStart
+
+- **[Worker](./worker/README.md)** - Running workflows and activities
+  - [Setup](./worker/setup.md) - KWorkerFactory, KWorker, registration
+
+### Reference
+
+- **[Testing](./testing.md)** - Unit testing, mocking activities, time skipping
+- **[Migration Guide](./migration.md)** - Migrating from Java SDK
+- **[API Parity](./api-parity.md)** - Java SDK comparison, gaps, not-needed APIs
+- **[Open Questions](./open-questions.md)** - API design decisions pending discussion
+
+## Quick Start
+
+```kotlin
+// Define activity interface - @ActivityMethod is optional
+@ActivityInterface
+interface GreetingActivities {
+    suspend fun composeGreeting(greeting: String, name: String): String
+}
+
+// Implement activity
+class GreetingActivitiesImpl : GreetingActivities {
+    override suspend fun composeGreeting(greeting: String, name: String): String {
+        return "$greeting, $name!"
+    }
+}
+
+// Define workflow interface - @WorkflowMethod is optional
+@WorkflowInterface
+interface GreetingWorkflow {
+    suspend fun getGreeting(name: String): String
+}
+
+// Implement workflow
+class GreetingWorkflowImpl : GreetingWorkflow {
+    override suspend fun getGreeting(name: String): String {
+        return KWorkflow.executeActivity(
+            GreetingActivities::composeGreeting,
+            KActivityOptions(startToCloseTimeout = 10.seconds),
+            "Hello", name
+        )
+    }
+}
+
+// Start worker - workflows and activities specified in options
+val worker = KWorker(
+    client,
+    KWorkerOptions(
+        taskQueue = "greetings",
+        workflows = listOf(GreetingWorkflowImpl::class),
+        activities = listOf(GreetingActivitiesImpl())
+    )
+)
+worker.start()
+
+// Execute workflow
+val result = client.executeWorkflow(
+    GreetingWorkflow::getGreeting,
+    KWorkflowOptions(workflowId = "greeting-123", taskQueue = "greetings"),
+    "Temporal"
+)
+```
+
+---
+
+**[Start Review →](./kotlin-idioms.md)**

kotlin/activities/README.md

@@ -0,0 +1,77 @@
+# Activities
+
+This section covers defining and implementing Temporal activities in Kotlin.
+
+## Overview
+
+Activities are the building blocks for interacting with external systems. The Kotlin SDK provides type-safe activity execution with suspend function support.
+
+## Documents
+
+| Document | Description |
+|----------|-------------|
+| [Definition](./definition.md) | Activity interfaces, typed and string-based execution |
+| [Implementation](./implementation.md) | Implementing activities, KActivity API, heartbeating |
+| [Local Activities](./local-activities.md) | Short-lived local activities |
+
+## Quick Reference
+
+### Basic Activity
+
+```kotlin
+// Define activity interface - @ActivityMethod is optional
+@ActivityInterface
+interface GreetingActivities {
+    suspend fun composeGreeting(greeting: String, name: String): String
+}
+
+// Use @ActivityMethod only when customizing the activity name
+@ActivityInterface
+interface CustomNameActivities {
+    @ActivityMethod(name = "compose-greeting")
+    suspend fun composeGreeting(greeting: String, name: String): String
+}
+
+// Implement activity
+class GreetingActivitiesImpl : GreetingActivities {
+    override suspend fun composeGreeting(greeting: String, name: String): String {
+        return "$greeting, $name!"
+    }
+}
+```
+
+### Calling Activities from Workflows
+
+```kotlin
+// Type-safe method reference
+val greeting = KWorkflow.executeActivity(
+    GreetingActivities::composeGreeting,
+    KActivityOptions(startToCloseTimeout = 30.seconds),
+    "Hello", "World"
+)
+
+// String-based (for cross-language interop)
+val result = KWorkflow.executeActivity<String>(
+    "composeGreeting",
+    KActivityOptions(startToCloseTimeout = 30.seconds),
+    "Hello", "World"
+)
+```
+
+### Key Patterns
+
+| Pattern | API |
+|---------|-----|
+| Execute activity | `KWorkflow.executeActivity(Interface::method, options, args)` |
+| Execute by name | `KWorkflow.executeActivity<R>("name", options, args)` |
+| Local activity | `KWorkflow.executeLocalActivity(Interface::method, options, args)` |
+| Heartbeat | `KActivity.executionContext.heartbeat(details)` |
+
+## Related
+
+- [Implementation](./implementation.md) - Suspend activity patterns
+- [Local Activities](./local-activities.md) - Short-lived activities
+
+---
+
+**Next:** [Activity Definition](./definition.md)