feat(scheduler): add TaskData typed wrapper for input data

Replace Map<String, String> inputData with a typed TaskData class that provides:
- Typed accessors (getString, getInt, getLong, getBoolean, getDouble)
- No silent nulls or manual parsing in tasks
- Builder DSL for ergonomic enqueue-time configuration
- Backward-compatible equals/hashCode and operator get

Update all usages across scheduler and testing modules, documentation, and fix
a pre-existing smart cast issue in TestDesktopTaskScheduler.

Author: kdroidFilter

docs/runtime/scheduler.md

@@ -91,7 +91,7 @@ Repeat at a fixed interval (minimum 15 minutes):
 ```kotlin
 scheduler.enqueue(
     TaskRequest.periodic("backup", 30.minutes) {
-        inputData("target", "/tmp/backup")
+        inputData { putString("target", "/tmp/backup") }
         retryPolicy(RetryPolicy.ExponentialBackoff())
         existingTaskPolicy(ExistingTaskPolicy.REPLACE)
     }
@@ -128,28 +128,37 @@ scheduler.enqueue(TaskRequest.onBoot("login-sync"))
 
 ### Input data
 
-Pass key-value pairs to tasks at enqueue time, then read them in `doWork()`:
+Pass typed key-value pairs to tasks at enqueue time via `TaskData`, then read them with typed accessors in `doWork()`:
 
 ```kotlin
 // Enqueue
 scheduler.enqueue(
     TaskRequest.periodic("sync", 1.hours) {
-        inputData("endpoint", "https://api.example.com")
-        inputData("token", "abc123")
+        inputData {
+            putString("endpoint", "https://api.example.com")
+            putString("token", "abc123")
+            putInt("retries", 3)
+            putBoolean("verbose", false)
+        }
     }
 )
 
 // In the task
 class SyncTask : DesktopTask {
     override suspend fun doWork(context: TaskContext): TaskResult {
-        val endpoint = context.inputData["endpoint"]
-        val token = context.inputData["token"]
+        val endpoint = context.inputData.getString("endpoint")
+            ?: return TaskResult.Failure("missing endpoint")
+        val token = context.inputData.getString("token")
+        val retries = context.inputData.getInt("retries", default = 3)
+        val verbose = context.inputData.getBoolean("verbose")
         // ...
         return TaskResult.Success
     }
 }
 ```
 
+Available typed accessors: `getString`, `getInt`, `getLong`, `getBoolean`, `getDouble`. All accept an optional `default` parameter (except `getString`, which returns `null` when absent).
+
 ### Task results and retry
 
 Return `TaskResult.Success`, `TaskResult.Failure`, or `TaskResult.Retry` from `doWork()`:
@@ -339,7 +348,7 @@ Builder DSL:
 
 | Method | Description |
 |--------|-------------|
-| `inputData(key, value)` | Attach a key-value pair, retrievable via `TaskContext.inputData`. |
+| `inputData { ... }` | Attach typed key-value pairs via `TaskData.Builder` (see [Input data](#input-data)). |
 | `retryPolicy(policy)` | Set the retry strategy (`ExponentialBackoff` or `Linear`). |
 | `existingTaskPolicy(policy)` | `KEEP` (default) or `REPLACE` if same task ID exists. |
 | `runImmediately(enabled)` | Run the task immediately when scheduled (periodic tasks only). Default: `false`. |
@@ -367,7 +376,7 @@ Builder DSL:
 | Property | Type | Description |
 |----------|------|-------------|
 | `taskId` | `String` | The unique task identifier. |
-| `inputData` | `Map<String, String>` | Key-value pairs from enqueue time. |
+| `inputData` | `TaskData` | Typed key-value data from enqueue time. Use `getString`, `getInt`, `getLong`, `getBoolean`, `getDouble`. |
 | `runAttemptCount` | `Int` | 1-based attempt counter (increments on retry). |
 
 ### `TaskResult`
@@ -475,7 +484,7 @@ dependencies {
 val result = TestTaskRunner.runTask(
     task = SyncTask(),
     taskId = "sync",
-    inputData = mapOf("endpoint" to "https://test.api"),
+    inputData = TaskData.Builder().putString("endpoint", "https://test.api").build(),
     runAttemptCount = 1,
 )
 assertEquals(TaskResult.Success, result)
@@ -598,7 +607,7 @@ constraintChecker.uninstall()
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `runTask(task, taskId?, inputData?, runAttemptCount?)` | `TaskResult` | Calls `doWork()` with a controlled `TaskContext`. |
+| `runTask(task, taskId?, inputData?, runAttemptCount?)` | `TaskResult` | Calls `doWork()` with a controlled `TaskContext`. `inputData` is a `TaskData` instance (default: `TaskData.EMPTY`). |
 
 ### `TestDesktopTaskScheduler`
 

scheduler-testing/src/main/kotlin/io/github/kdroidfilter/nucleus/scheduler/testing/TestDesktopTaskScheduler.kt

@@ -280,8 +280,9 @@ public class TestDesktopTaskScheduler :
         val fires = mutableListOf<PendingFire>()
 
         for ((taskId, request) in tasks) {
-            if (request.type != TaskRequest.Type.PERIODIC || request.interval == null) continue
-            val intervalMs = request.interval.inWholeMilliseconds
+            val interval = request.interval
+            if (request.type != TaskRequest.Type.PERIODIC || interval == null) continue
+            val intervalMs = interval.inWholeMilliseconds
             val baseMs = enqueueTimeMs[taskId] ?: 0L
 
             // Compute the next fire time after current virtualTimeMs

scheduler-testing/src/main/kotlin/io/github/kdroidfilter/nucleus/scheduler/testing/TestTaskRunner.kt

@@ -2,6 +2,7 @@ package io.github.kdroidfilter.nucleus.scheduler.testing
 
 import io.github.kdroidfilter.nucleus.scheduler.DesktopTask
 import io.github.kdroidfilter.nucleus.scheduler.TaskContext
+import io.github.kdroidfilter.nucleus.scheduler.TaskData
 import io.github.kdroidfilter.nucleus.scheduler.TaskResult
 
 /**
@@ -13,7 +14,7 @@ import io.github.kdroidfilter.nucleus.scheduler.TaskResult
  * val result = TestTaskRunner.runTask(
  *     task = SyncTask(),
  *     taskId = "sync",
- *     inputData = mapOf("endpoint" to "https://test.api"),
+ *     inputData = TaskData.Builder().putString("endpoint", "https://test.api").build(),
  * )
  * assertEquals(TaskResult.Success, result)
  * ```
@@ -24,13 +25,13 @@ public object TestTaskRunner {
      *
      * @param task the task to execute
      * @param taskId the task identifier passed in the context (default: `"test-task"`)
-     * @param inputData key-value pairs available via [TaskContext.inputData]
+     * @param inputData typed key-value data available via [TaskContext.inputData]
      * @param runAttemptCount 1-based attempt counter (default: `1`)
      */
     public suspend fun runTask(
         task: DesktopTask,
         taskId: String = "test-task",
-        inputData: Map<String, String> = emptyMap(),
+        inputData: TaskData = TaskData.EMPTY,
         runAttemptCount: Int = 1,
     ): TaskResult {
         val context =

scheduler-testing/src/test/kotlin/io/github/kdroidfilter/nucleus/scheduler/testing/SchedulerTestingTest.kt

@@ -4,6 +4,7 @@ import io.github.kdroidfilter.nucleus.scheduler.DesktopTask
 import io.github.kdroidfilter.nucleus.scheduler.DesktopTaskScheduler
 import io.github.kdroidfilter.nucleus.scheduler.ExistingTaskPolicy
 import io.github.kdroidfilter.nucleus.scheduler.TaskContext
+import io.github.kdroidfilter.nucleus.scheduler.TaskData
 import io.github.kdroidfilter.nucleus.scheduler.TaskRegistry
 import io.github.kdroidfilter.nucleus.scheduler.TaskRequest
 import io.github.kdroidfilter.nucleus.scheduler.TaskResult
@@ -38,7 +39,7 @@ class RetryTask : DesktopTask {
 }
 
 class InputEchoTask : DesktopTask {
-    var receivedData: Map<String, String> = emptyMap()
+    var receivedData: TaskData = TaskData.EMPTY
 
     override suspend fun doWork(context: TaskContext): TaskResult {
         receivedData = context.inputData
@@ -79,9 +80,9 @@ class TestTaskRunnerTest {
             val task = InputEchoTask()
             TestTaskRunner.runTask(
                 task = task,
-                inputData = mapOf("key" to "value"),
+                inputData = TaskData.Builder().putString("key", "value").build(),
             )
-            assertEquals(mapOf("key" to "value"), task.receivedData)
+            assertEquals("value", task.receivedData.getString("key"))
         }
 
     @Test
@@ -206,7 +207,7 @@ class TestDesktopTaskSchedulerTest {
 
             val request =
                 TaskRequest.periodic("success", 1.hours) {
-                    inputData("key", "value")
+                    inputData { putString("key", "value") }
                 }
             DesktopTaskScheduler.enqueue(request)
 
@@ -224,12 +225,12 @@ class TestDesktopTaskSchedulerTest {
 
             DesktopTaskScheduler.enqueue(
                 TaskRequest.periodic("success", 1.hours) {
-                    inputData("version", "1")
+                    inputData { putString("version", "1") }
                 },
             )
             DesktopTaskScheduler.enqueue(
                 TaskRequest.periodic("success", 2.hours) {
-                    inputData("version", "2")
+                    inputData { putString("version", "2") }
                 },
             )
 
@@ -246,12 +247,12 @@ class TestDesktopTaskSchedulerTest {
 
             DesktopTaskScheduler.enqueue(
                 TaskRequest.periodic("success", 1.hours) {
-                    inputData("version", "1")
+                    inputData { putString("version", "1") }
                 },
             )
             DesktopTaskScheduler.enqueue(
                 TaskRequest.periodic("success", 2.hours) {
-                    inputData("version", "2")
+                    inputData { putString("version", "2") }
                     existingTaskPolicy(ExistingTaskPolicy.REPLACE)
                 },
             )
@@ -277,14 +278,16 @@ class TestDesktopTaskSchedulerTest {
 
                 DesktopTaskScheduler.enqueue(
                     TaskRequest.periodic("echo", 1.hours) {
-                        inputData("endpoint", "https://test.api")
-                        inputData("token", "abc123")
+                        inputData {
+                            putString("endpoint", "https://test.api")
+                            putString("token", "abc123")
+                        }
                     },
                 )
 
                 scheduler.runTask("echo", customRegistry)
-                assertEquals("https://test.api", task.receivedData["endpoint"])
-                assertEquals("abc123", task.receivedData["token"])
+                assertEquals("https://test.api", task.receivedData.getString("endpoint"))
+                assertEquals("abc123", task.receivedData.getString("token"))
             } finally {
                 scheduler.uninstall()
             }

scheduler/src/main/kotlin/io/github/kdroidfilter/nucleus/scheduler/TaskContext.kt

@@ -4,11 +4,11 @@ package io.github.kdroidfilter.nucleus.scheduler
  * Execution context passed to [DesktopTask.doWork].
  *
  * @property taskId the unique identifier of this task
- * @property inputData key-value data passed at enqueue time
+ * @property inputData typed key-value data passed at enqueue time
  * @property runAttemptCount 1-based attempt counter (1 = first run, 2 = first retry, etc.)
  */
 public data class TaskContext(
     val taskId: String,
-    val inputData: Map<String, String> = emptyMap(),
+    val inputData: TaskData = TaskData.EMPTY,
     val runAttemptCount: Int = 1,
 )

scheduler/src/main/kotlin/io/github/kdroidfilter/nucleus/scheduler/TaskData.kt

@@ -0,0 +1,119 @@
+package io.github.kdroidfilter.nucleus.scheduler
+
+/**
+ * Typed key-value container for task input data.
+ *
+ * Values are stored internally as strings (backed by a `.properties` file) but
+ * retrieved via typed accessors, eliminating manual parsing and silent `null`s.
+ *
+ * Build instances with [Builder]:
+ * ```kotlin
+ * TaskRequest.periodic("sync", 1.hours) {
+ *     inputData {
+ *         putString("endpoint", "https://api.example.com")
+ *         putInt("retries", 3)
+ *         putBoolean("verbose", true)
+ *     }
+ * }
+ * ```
+ *
+ * Read values in [DesktopTask.doWork]:
+ * ```kotlin
+ * val endpoint = context.inputData.getString("endpoint") ?: return TaskResult.Failure("missing endpoint")
+ * val retries  = context.inputData.getInt("retries", default = 3)
+ * ```
+ */
+public class TaskData internal constructor(
+    internal val map: Map<String, String> = emptyMap(),
+) {
+    // -- Typed accessors ------------------------------------------------------
+
+    /** Returns the string value for [key], or `null` if absent. */
+    public fun getString(key: String): String? = map[key]
+
+    /** Returns the int value for [key], or [default] if absent or not parseable. */
+    public fun getInt(
+        key: String,
+        default: Int = 0,
+    ): Int = map[key]?.toIntOrNull() ?: default
+
+    /** Returns the long value for [key], or [default] if absent or not parseable. */
+    public fun getLong(
+        key: String,
+        default: Long = 0L,
+    ): Long = map[key]?.toLongOrNull() ?: default
+
+    /** Returns the boolean value for [key], or [default] if absent or not parseable. */
+    public fun getBoolean(
+        key: String,
+        default: Boolean = false,
+    ): Boolean = map[key]?.toBooleanStrictOrNull() ?: default
+
+    /** Returns the double value for [key], or [default] if absent or not parseable. */
+    public fun getDouble(
+        key: String,
+        default: Double = 0.0,
+    ): Double = map[key]?.toDoubleOrNull() ?: default
+
+    // -- Convenience ----------------------------------------------------------
+
+    /** Returns the string value for [key], or `null` if absent. Shorthand for [getString]. */
+    public operator fun get(key: String): String? = map[key]
+
+    /** Returns `true` if no key-value pairs are present. */
+    public fun isEmpty(): Boolean = map.isEmpty()
+
+    /** Returns `true` if at least one key-value pair is present. */
+    public fun isNotEmpty(): Boolean = map.isNotEmpty()
+
+    // -- Builder --------------------------------------------------------------
+
+    /** Builds a [TaskData] instance by accumulating typed key-value pairs. */
+    public class Builder {
+        private val map = mutableMapOf<String, String>()
+
+        public fun putString(
+            key: String,
+            value: String,
+        ): Builder = apply { map[key] = value }
+
+        public fun putInt(
+            key: String,
+            value: Int,
+        ): Builder = apply { map[key] = value.toString() }
+
+        public fun putLong(
+            key: String,
+            value: Long,
+        ): Builder = apply { map[key] = value.toString() }
+
+        public fun putBoolean(
+            key: String,
+            value: Boolean,
+        ): Builder = apply { map[key] = value.toString() }
+
+        public fun putDouble(
+            key: String,
+            value: Double,
+        ): Builder = apply { map[key] = value.toString() }
+
+        public fun build(): TaskData = TaskData(map.toMap())
+    }
+
+    // -- Equality & companion -------------------------------------------------
+
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other !is TaskData) return false
+        return map == other.map
+    }
+
+    override fun hashCode(): Int = map.hashCode()
+
+    override fun toString(): String = "TaskData($map)"
+
+    public companion object {
+        /** Empty [TaskData] with no key-value pairs. */
+        public val EMPTY: TaskData = TaskData()
+    }
+}