solti-runner 0.0.1

Solti SDK runner plugin trait.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# solti-runner
Runner plugin interface, routing, and execution metrics for the solti task system.
Sits between the domain model (`solti-model`) and the orchestration layer (`solti-core`), providing a stable plugin boundary.

## Architecture
```text
  TaskSpec ──► RunnerRouter ──► Runner::build_task() ──► TaskRef
                   │                    ▲
                   │  label matching    │  BuildContext
                   │  + supports()      │  (env + metrics)
                   ▼                    │
               RunnerEntry          MetricsHandle
               (runner + labels)    (Arc<dyn MetricsBackend>)
```

## Routing flow
```text
  RunnerRouter::build(spec)
    │
    ├─ 1. reject TaskKind::Embedded          (requires submit_with_task)
    │
    ├─ 2. for each registered runner:
    │      ├─ runner.supports(spec)?         kind check
    │      └─ selector.matches(labels)?      label matching (if selector set)
    │
    ├─ 3. first match → runner.build_task(spec, ctx)
    │
    └─ 4. no match → RunnerError::NoRunner
```

## Key types

| Type              | Purpose                                                                                    |
|-------------------|--------------------------------------------------------------------------------------------|
| `Runner`          | Trait: `name()`, `supports()`, `build_task()`, `build_run_id()`                            |
| `RunnerRouter`    | Selects runner by supports() + label matching                                              |
| `BuildContext`    | Shared dependencies: `RunnerEnv` + `MetricsHandle`                                         |
| `RunId`           | Human-readable id: `{runner}-{slot}-{seq}`                                                 |
| `RunnerError`     | Error enum: `NoRunner`, `UnsupportedKind`, `InvalidSpec`, `Internal`, `MissingField`, `Io` |
| `MetricsBackend`  | Trait: `record_task_started`, `record_task_completed`, `record_runner_error`               |
| `MetricsHandle`   | `Arc<dyn MetricsBackend>` - cloneable shared handle                                        |
| `NoOpMetrics`     | Zero-size backend (`#[inline(always)]`)                                                    |
| `RunnerType`      | Metric label: `Subprocess`, `Wasm`, `Container`                                            |
| `TaskOutcome`     | Metric label: `Success`, `Failure`, `Canceled`, `Timeout`                                  |

## Runner trait
```text
  trait Runner: Send + Sync {
      fn name(&self) -> &'static str;
      fn supports(&self, spec: &TaskSpec) -> bool;
      fn build_task(&self, spec: &TaskSpec, ctx: &BuildContext) -> Result<TaskRef, RunnerError>;
      fn build_run_id(&self, slot: &str) -> RunId;   // default: make_run_id(name, slot)
  }
```

## Error model
```text
  Variant            When                                          
  ───────            ────                                          
  NoRunner           no registered runner matches the spec         
  UnsupportedKind    runner does not handle this TaskKind          
  InvalidSpec        spec is malformed for this runner             
  MissingField       required field missing from spec              
  Internal           unexpected runner error                       
  Io                 I/O error during task setup (From<io::Error>) 
```

## Metrics interface
```text
  trait MetricsBackend: Send + Sync + 'static {
      fn record_task_started(&self, runner_type: RunnerType);
      fn record_task_completed(&self, runner_type: RunnerType, outcome: TaskOutcome, duration_ms: u64);
      fn record_runner_error(&self, runner_type: RunnerType, error_kind: &str);
  }
```

Default backend: `NoOpMetrics` (zero-size, `#[inline(always)]` - compiles to nothing).

Production backend: `solti-prometheus::PrometheusMetrics`.

## Notes
- Runners are checked in registration order; the first match wins.
- `TaskKind::Embedded` is not routable: use `SupervisorApi::submit_with_task` directly.
- `RunId` sequence is process-global, monotonically increasing, starts at 1.
- `BuildContext` defaults: empty `RunnerEnv` + `NoOpMetrics`.