57 lines
2.2 KiB
Markdown
57 lines
2.2 KiB
Markdown
|
# Node Boot Lifecycle Contract
|
||
|
|
|
||
|
|
This document defines the behavioral contract for node boot. It covers the
|
||
|
|
observable transition from container start to `NodeAvailable`, and the failure
|
||
|
|
cases that keep a node out of the candidate run pool.
|
||
|
|
|
||
|
|
## Boot Formation
|
||
|
|
|
||
|
|
- A node boot attempt starts when the node process is launched in the intended
|
||
|
|
pool.
|
||
|
|
- A boot attempt emits either `NodeAvailable` or a typed node boot fault.
|
||
|
|
- It never emits `NodeAvailable` before required local resources are ready.
|
||
|
|
- It never allows run provisioning to race ahead of node availability.
|
||
|
|
|
||
|
|
## Required Readiness Facts
|
||
|
|
|
||
|
|
- The Rust node process is alive.
|
||
|
|
- The swactor runtime can receive control messages.
|
||
|
|
- The node has a stable `node_id` known to the orchestrator.
|
||
|
|
- The arena is created and mapped in the node process.
|
||
|
|
- The GPU worker is ready, or the implementation has an explicit deferred
|
||
|
|
worker-start policy with the same run-level readiness guarantee.
|
||
|
|
- The iroh endpoint is initialized and bound to the node identity.
|
||
|
|
- The SWIM participant has joined or is joining the intended pool.
|
||
|
|
- The node can accept run provisioning.
|
||
|
|
|
||
|
|
## Non-Readiness Facts
|
||
|
|
|
||
|
|
- `NodeAvailable` does not mean weights are present.
|
||
|
|
- `NodeAvailable` does not mean a role is configured.
|
||
|
|
- `NodeAvailable` does not mean run edges are established.
|
||
|
|
- `NodeAvailable` does not mean the node has been selected by a `RunPlan`.
|
||
|
|
|
||
|
|
## Failure Behavior
|
||
|
|
|
||
|
|
- Arena construction failure rejects node availability.
|
||
|
|
- Worker startup failure rejects node availability unless worker startup is
|
||
|
|
explicitly deferred.
|
||
|
|
- Transport endpoint failure rejects node availability.
|
||
|
|
- Missing or invalid node identity rejects node availability.
|
||
|
|
- A node that is boot-faulted is not eligible for run planning.
|
||
|
|
|
||
|
|
## Authority
|
||
|
|
|
||
|
|
- The node owns local boot resources.
|
||
|
|
- The orchestrator owns whether a booted node is part of the intended candidate
|
||
|
|
pool.
|
||
|
|
- A node does not self-assign stages, edges, or layer ranges during boot.
|
||
|
|
|
||
|
|
## Test Direction
|
||
|
|
|
||
|
|
Tests should drive the boot component through public resource outcomes and
|
||
|
|
observe emitted lifecycle events. Successful tests should assert that
|
||
|
|
`NodeAvailable` appears only after the required readiness facts. Failure tests
|
||
|
|
should inject one failed resource at a time and assert a typed boot fault with
|
||
|
|
no `NodeAvailable`.
|