OXYGENHUB

Spec: runner tiers, declines and waiting reasons as built 630ee66034b2

§11 records what is done (tiers, §11.5, the waiting reasons of §11.4)
and how: the decline endpoint, the profile hash, the ten-minute lapse,
unplaceable as an error, the 15-second placement pass. refs #36
Author
Andy McCall @andymccall <[email protected]>
When
· 2026-10-05 00:58 UTC
Signature
✔ signed by Andy McCall
Hash
630ee66034b2a27711318b21906453680d01c5fa58e43beb5e98560a30a0948a
Depends on
1abadd4a2fa6 a083cc802892 fd2d4822f7f3
Depended on by
89171fca079c
In bookmarks
main newer-pipeline push-uses-login
In tags
v0.2.0 v0.3.0 v0.3.1 v0.4.0 v0.5.0 v0.5.1 v0.5.2 v0.5.3
Edits
3 atoms, 0 tree operations, 1 file

Browse the tree at this change

hide whitespace changes
modified docs/spec.md +10 −1
… 
429 unchanged lines
430 430 
   MUST be rejected by policy verification.
431 431 
5. Hermetic Network Isolation: Jobs configured with network "isolated" MUST
432 432 
   have outgoing TCP SYN and UDP packets dropped at the hypervisor boundary.
433 - 
## 11. Runner Capabilities and Placement (proposed 2026-10-04; §11.2 and `arch` of §11.3 done the same day, oxygenflow#36)
433 + 
## 11. Runner Capabilities and Placement (proposed 2026-10-04; §11.2 and `arch` of §11.3 done the same day; tiers of §11.1, §11.5 and the waiting reasons of §11.4 done 2026-10-05, oxygenflow#36)
434 434 

    

  
    

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

    

  
    

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

    

  
    

      
      
      …
      
70 unchanged lines

    

  
    

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

    

  
    

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

    

  
    

      509
      509
       
      

    

  
    

      
      510
      +
      
As built: the runner sends `POST /api/v1/flow/jobs/{id}/decline` with

    

  
    

      
      511
      +
      
`{"reason": …}` before it fetches anything. The profile is a hash of the

    

  
    

      
      512
      +
      
tiers, images, architecture, labels and capacity a runner claims with.

    

  
    

      
      513
      +
      
A decline also lapses after ten minutes, so a passing reason such as

    

  
    

      
      514
      +
      
memory in use does not bar a runner for good. An unplaceable job ends

    

  
    

      
      515
      +
      
with status `error` and an error beginning `unplaceable:`. The hub

    

  
    

      
      516
      +
      
works out why each ready job waits every 15 seconds, and the run page and

    

  
    

      
      517
      +
      
the API (`waiting`) show it.

    

  
    

      
      518
      +
      

    

  
    

      510
      519
       
      
### 11.6 Conformance

    

  
    

      511
      520
       
      

    

  
    

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

    

  
    

      
      
      …
      
10 unchanged lines