zacheryasc/swactor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
swactor/specs/mvp_system/node_boot_lifecycle_contract.md
Zachery Aaron Shores-Chmielewski b5de4c9bd6 docs(mvp): lay out mvp-system spec and contracts 
Add MVP_SYSTEM_SPEC plus per-component contract docs (arena manager, device bridge,
gpu worker ctl/ingress/egress/process-adapter, orchestrator run-fsm/token-endpoint,
run plan, stage controller, tx_rx edge, weights). Scaffold the guarantee tests against
the (empty) mvp-system crate.


Signed-off-by: Zachery Aaron Shores-Chmielewski <zacheryasc@gmail.com>
2026-06-23 11:12:45 +04:00

2.2 KiB
Raw Blame History

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.