Plan の構築
Plan construction は Manifest を読み込んで終わる処理ではありません。 runtime が始まる前に model composition、plugin capability、typed binding、schedule、state authority を解決し、run 中に同じ構造検査を繰り返さない状態へ freeze します。
構築フロー
現在の SimulationBuilder::build() は概念的に次の順で進みます。
Manifest の検証
最初に Manifest schema と model path を検証します。
Manifest schema 3.3 でも model composition と physics timestep を再定義せず、MJCF を物理モデルの source of truth とします。
low-level StateClaim や schedule も user field として受け取らず、Component と registered runtime capability から導出します。
この境界によって「Component config と別の schedule declaration が矛盾する」という二重 source of truth を作りません。
parameter_overlays がある場合は、Manifest validation の直後に versioned artifact を resource として読み込みます。
persistent overlay は programmatic Builder overlay と同じ typed target contract へ正規化されるため、以後の Component と MuJoCo construction は calibration artifact の出所を特別扱いしません。
Extension の Declare
Manifest に plugin class があれば extension loader を介して instance を生成します。 Declare phase では Component type など、後続の Manifest interpretation に必要な capability を registry へ登録できます。 extension は factory 登録後に project-local Component profile catalog も登録できます。
Declare が終わる前に Component declaration を確定すると、extension-owned Component type を unknown type と誤判定します。 そのため Component resolution は capability declaration の後に行います。
Component の解決
各 ComponentDeclaration は registry から ComponentFactory を取得し、最初に profile / profiles を effective config へ解決します。
複数 facet の profile は conflict-free に合成し、異なる profile が同じ leaf field に異なる値を設定した場合は拒否します。
instance config は合成済み profile に対する明示 override です。
Component が assemblies から参照されている場合は、profile composition の後に transmission 由来の effective field を materialize します。
例えば wheel assembly は wheel radius から logical_units_per_joint_unit を導出し、parallel actuator assembly は device profile の current conversion と actuator_count から per-actuator feedback semantics を導出します。
assembly が ownership を持つ field を instance config に重複記述した場合は construction error にします。
calibration が component_config target を持つ場合は、assembly resolution の後に ComponentParameterOverlay を effective config へ適用します。
この順序により profile 由来の numeric scalar を instance YAML へ複製せず calibration target にできます。
その後 ComponentFactory が effective config を ComponentDefinition へ解決します。
definition は descriptor に加えて Device factory、actuator endpoint、PrescribedState factory などの runtime contribution を返せます。
Component config の unknown field や invalid parameter はこの段階で stable BuildError category に変換されます。
resolved descriptor は選択した profile facet/ID と effective config hash を保持します。
Extension の Configure
Configure phase では resolved Component descriptor を見た上で extension runtime を構成できます。 物理モデルの構造変更はこの API から行わず、MJCF / MuJoCo model composition で表します。
Model assembly と MuJoCo compile
model.path は MuJoCo ResourceProvider に直接渡し、mj_parseXML で mjSpec にします。
nested include、model asset、attach、asset loading、namespace validation は MuJoCo 自身が処理します。
actuator assembly がある場合は、parse 後の mjSpec に transmission 由来の actuator gear を materialize します。
assembly-owned actuator の raw MJCF に非既定 gear が書かれている場合は、同じ物理 transmission の二重 ownership として拒否します。
calibration が physical target を持つ場合は、その後に typed MujocoParameterOverlay を mjSpec に適用し、最後に mj_compile で model にします。
body/joint/geom に加えて actuator gear/force range、position-servo gain、native DC motor の electrical/controller parameter も typed target として扱えます。
Fibril の physics grid は compile 後の mjModel.opt.timestep から導出します。
parse failure と compile failure は別の diagnostic code を持ちます。
compile が成功して warning だけを返した場合は failure にせず ConstructionWarning として Plan に保持します。
Typed binding の解決
compile 後の model に対して、Plan-defined MuJoCo reference を object kind 付きで一度だけ解決します。 Device、PrescribedState、ActuatorDriver、Interaction などが要求した name は capability ごとに解決し、その factory と同じ value object に保持します。 actuator endpoint は解決済み actuator ID を直接保持します。 Plan 全体を横断する role/owner keyed binding registry は持ちません。
runtime が Component config の string name から毎 step mj_name2id を繰り返す設計にはしません。
Global invariant の検証
capability-local な resolved binding を入力に、state authority、PrescribedState、actuator endpoint、schedule、execution mode、Device model compatibility、domain runtime を検証します。
validation が成功した後に Plan を生成するため、run 開始後に構造的不整合を発見する範囲を減らせます。 runtime failure がなくなるという意味ではなく、runtime input や extension logic に依存する invariant は実行中にも検査されます。
Provenance と freeze
root model、scenario、persistent parameter overlay の明示的 resource hash に加え、compiled model hash、Manifest hash、parameter-set hash、MuJoCo version、resolved extension identity、episode seed を RunProvenance に保持します。
parameter-set hash には effective Component config hash、選択 profile facet/ID、resolved actuator assembly、resolved Extension の ID、version、dependencies、config hash、typed MuJoCo/Component parameter overlay の target identity と value が入ります。
このため Manifest に書かれていない programmatic Extension config も Plan の parameter identity に反映されます。
include や attach を含む最終的な model identity は serialized compiled model の hash を authoritative とします。
最後に immutable SimulationPlan を生成します。
freeze 後は extension loader や registry capability を追加できません。