Component と extension

Component と SimulationExtension は、Manifest から runtime capability を追加する二つの abstraction です。 Component は再利用可能な simulation unit、Extension は application 固有の composition boundary として役割を分けます。

Component の lifecycle

Manifest の declaration は次の形です。

components:
  - id: front_lrf
    type: fibril_sim/rangefinder
    config:
      sensor: front_rangefinder_sensor
      period_s: 0.01
      range_min: 0.05
      range_max: 10.0

ComponentRegistry は type から ComponentFactory を取得します。 factory は instance_id と raw YAML config を解釈し、ComponentDefinition を返します。

ComponentDefinition は polymorphic runtime object ではなく、ComponentDescriptor と ComponentContributions を束ねる construction-time value object です。 component 固有の polymorphism は ComponentFactory で終端し、factory が config validation 後に その instance の全 contribution を値として確定します。 active SimulationInstance を直接生成したり、compile 済みでない MuJoCo object ID を保持したりしません。

ComponentContributions の内容

現在の主要な capability は次のとおりです。

• Device runtime の factory
• actuator endpoint の descriptor
• actuator driver runtime の factory
• external input source の descriptor
• PrescribedState runtime の factory
• Interaction runtime の factory

新しい contribution role を追加するときは ComponentDefinition の virtual method を増やすのではなく、 ComponentContributions の value field として追加します。 これにより capability 拡張を Component subclass の vtable 変更から切り離します。

SimulationBuilder は component ごとの contribution を別の中間表へ flatten しません。 Component 解決時に prescribed state、Device、ExternalInput source、Interaction を Builder の同じ capability registry へ登録し、actuator endpoint と ActuatorDriver も ID 順の canonical registry に格納します。 Extension の Configure で追加された capability も同じ registry に入るため、component 由来と extension 由来を後から再マージする段階はありません。

schedule と state authority は capability descriptor から導出します。 Manifest に同じ情報を別 field として持たせないことで、Component implementation と user configuration の source of truth を一本化します。

Device factory の責務

Device factory は DeviceDescriptor と typed MujocoBindingRequest を宣言します。 construction は binding request を compile 済み model に対して解決し、factory の validate_model() を呼びます。

run ごとの DeviceRuntime は resolved binding set と episode seed を受け取って生成します。 runtime 内で object name lookup を再実行する必要はありません。

PrescribedState factory の責務

PrescribedState factory は stable ID、自分が所有する StateClaim、binding request、model validation、run-local runtime creation を一つの capability として提供します。

この形にした理由は、StateClaim と enforcement implementation を別々に登録させないためです。 metadata claim だけが存在し runtime enforcement がない構成は construction で成立しません。

SimulationExtension の lifecycle

Extension は Declare と Configure の二段階です。

Declare では Component type など Manifest interpretation に必要な capability を登録します。 Configure では resolved Component descriptor を参照し、prescribed state、Device、ExternalInput source、domain state、Interaction、Observer などを構成できます。

Extension 間の hard dependency は dependencies() で extension ID を列挙します。 dependency は別 plugin を自動 load する指定ではなく、依存先も同じ build に追加されている必要があります。 Builder は dependency graph を topological order に解決し、その順序を Declare と Configure の両方に使います。 依存関係のない Extension 同士は stable extension ID 順に処理されるため、Manifest の記載順を semantic ordering として使いません。

pluginlib は fibril_sim_ament の integration concern です。 fibril_sim_mujoco 自体は pluginlib に依存せず、SimulationExtensionLoader abstraction を受け取ります。

Extension は arbitrary mjSpec mutation を construction capability として追加しません。 model structure と nominal physical parameter は MJCF が所有し、calibration の parameter variation だけを build 開始前に固定された typed MujocoParameterOverlay として適用します。 これにより Extension dependency は capability composition の順序を表し、model field の上書き優先順位には使いません。

Extension identity の扱い

Builder は Declare より前に extension ID、version、dependency set、config hash を resolved identity として固定します。 Plan inspection schema 2.2 はこの resolved identity を保持します。 version が空の extension は unversioned として明示されます。

config_hash は Manifest 経由と SimulationBuilder::add_extension() による programmatic composition の両方で同じように計算されます。 parameter_set_hash は resolved extension identity を入力にするため、同じ Manifest に programmatic Extension を追加した場合も extension config の差を識別できます。

extension behavior を replay や calibration の比較対象に含める場合は、stable version identity を実装して source/build revision と合わせて追跡できるようにします。