Spec §11: runner capabilities and placement fd2d4822f7f3

   have outgoing TCP SYN and UDP packets dropped at the hypervisor boundary.

## 11. Runner Capabilities and Placement (proposed 2026-10-04)

A runner MUST never take a job it cannot run or cannot finish well: the

wrong architecture, no hardware virtualisation for the MicroVM tier, too

little memory, an image it does not hold, or a machine too slow for the

job's time limit. Today a runner reports its architecture, OS, labels,

job slots, memory and vCPUs when it registers and on each claim, and a

claim carries the tiers it can run, the memory and vCPUs free now, and

the images it holds; the hub matches tier, room, labels, scope and image.

What is missing: architecture is reported but never matched (an image's

architecture is implicit in its bytes), a pipeline cannot say which

architecture it needs or offer a rootfs per architecture, speed and load

play no part, and a runner cannot decline a job it was handed.

### 11.1 Capability Profile

At registration and on every claim a runner sends its profile:

| Field | Meaning |

|---|---|

| `arch`, `os`, `kernel` | `x86_64`, `aarch64`, `riscv64`, …; the kernel release |

| `tiers` | The sandbox tiers it can honour: `microvm` only with `/dev/kvm` usable (a board without KVM, such as an OrangePi RV2, offers `syscall`, §4.2, and `wasm`) |

| `memory_mib`, `cpus`, `max_jobs` | What its jobs share |

| `images` | The rootfs images it holds, each with the architecture its manifest records (§11.2) |

| `labels` | As §3.1 |

| `speed` | A class from 1 (slow) to 5 (fast), measured at `flow runner register` and `flow runner bench` by a fixed workload (BLAKE3 over 256 MiB and the compilation of a fixed C file), bucketed so that two machines of the same class finish a job within a factor of two of each other |

| `load` | The 1-minute load average divided by `cpus`, memory free now, jobs running |

### 11.2 Image Manifests Carry the Architecture

`flow rootfs import` reads the ELF header of the image's `/bin/sh` and

records its architecture in the CAS manifest beside the hash. A runner

refuses to import an image for another architecture (there is no

emulation tier). An image imported before this section has no recorded

architecture and is treated as the importing runner's.

### 11.3 Job Requirements

Hard requirements, all of which a runner MUST satisfy to be offered the

job: the sandbox's tier, its rootfs (hence the image's architecture),

`memory-limit`, `cpus`, every `runs-on` label of the job and its sandbox,

and the runner's scope (OxygenHub spec §13.2). Two additions to the

language:

- `arch "riscv64"` on a sandbox pins the architecture; without it the

  architecture is the rootfs image's.

- A rootfs per architecture: `rootfs { x86_64 "cas://blob/…"; riscv64 "cas://blob/…" }`.

  The job runs on whichever architecture takes it; the receipt and the

  provenance record the architecture and image used, and a check's

  description names them.

Soft requirements guide placement but never block it: a job's `timeout`

against the runner's speed class. The hub keeps, per job hash and speed

class, the median duration of past runs; a runner whose class predicts a

duration over the limit is offered the job only when no better runner

is free.

### 11.4 Placement

The hub filters by the hard requirements, then ranks the runners that

remain: idle before busy (`load`), a higher speed class first, a runner

already holding the image before one that must fetch it (§5), fewer jobs

waiting on it first. A job no runner can satisfy waits and the queue

says what it waits for: tier, architecture, image, memory, labels or

scope, so the gap is visible rather than a silent stall.

### 11.5 Declining

A runner double-checks a claim before it starts: the architecture, that

`/dev/kvm` opens for the MicroVM tier, that the image's blob is present

and verifies, that the memory is free. If any check fails it answers the

hub with `declined` and a reason instead of running and failing; the hub

re-queues the job, never offers it to that runner again until its

profile changes, records the decline on the runner's page, and after

three declines by different runners marks the job `unplaceable` with the

reasons. A decline is never a failed check on the state.

### 11.6 Conformance

1. Architecture Safety: a job whose image is `x86_64` MUST never be

   offered to a `riscv64` runner, with or without the image copied there.

2. Tier Safety: a runner without `/dev/kvm` MUST NOT be offered a

   MicroVM job, and MUST decline one if handed it.

3. Room: a job whose `memory-limit` exceeds the runner's free memory

   MUST wait, not be killed.

4. Visibility: a job nobody can take MUST say why on the queue within

   one scheduling pass.

5. Preference: with two idle runners that both satisfy a job, the hub

   MUST offer it to the higher speed class, and to the one holding the

   image when classes tie.