Package の責務境界

package boundary は repository の整理都合ではなく、runtime dependency と責務の contract です。 特に core runtime へ ROS 2、pluginlib、ament lookup を持ち込まないことが headless test と integration の共通化に効きます。

Package	Responsibility
fibril_mujoco_vendor	pinned MuJoCo runtime と CMake export（ForteFibre/external_repo にあり、部内 apt リポジトリから入れる）
iceoryx2_vendor	pinned iceoryx2 C++ runtime と same-host IPC transport dependency（同上）
fibril_sim_core	exact simulation time、schedule、named RNG、latency queue、transaction/deferred primitive、provenance hashing
fibril_sim_mujoco	Manifest、Builder、Plan、Instance、MuJoCo construction、binding、runtime lifecycle、state authority、Device/ActuatorDriver/Domain contract
fibril_sim_models	standard virtual hardware、reduced-order physical model、MuJoCo model plugin、generic profile catalog、reusable MJCF preset
fibril_sim_runtime	SimulationRuntime、SimulationHost owner thread、same-host typed IPC SimulationServer / SimulationConnection boundary、runtime control
fibril_sim_ament	ament resource resolution、native MuJoCo package:// Resource Provider、pluginlib extension loader、standard ament-backed SimulationPlan composition
fibril_sim_description	MJCF を正本とした ROS 向け kinematic description と URDF projection
fibril_sim_trace	semantic trace の MCAP persistence
fibril_sim_diagnostics	D1/D2 comparison、first-divergence report、replay diagnostics、named trace signal query contract
fibril_sim_msgs	simulation-specific ROS message definition
fibril_sim_ros	/clock、DeviceOutput publisher、ingress-only subscription、rosbag2 adapter
fibril_sim_testing	reusable fixture、bench asset、SIL bench、architecture acceptance test
fibril_sim_calibration	calibration request contract、recorded episode alignment、rollout objective、parameter sweep、Ceres integration、held-out validation、caller-supplied Plan/decoder に対する calibration execution
fibril_sim_experiment	canonical model に対する explicit parameter variant 実験、trace-derived metric、result manifest
fibril_sim_cli	C++ executable frontend / composition root。fibril_sim command surface、argument parsing、human/versioned JSON presentation、exit-code mapping
fibril_sim_render	optional EGL offscreen rendered camera extension
fibril_sim_viewer	SimulationConnection から runtime-owned presentation と copied render state を受け取る optional interactive debug viewer
fibril_sim_video	SimulationConnection の render state を使う optional headless MP4 recorder
compatible_sim/*	production-facing ROS API を維持し、Fibril Simulation IPC を hardware transport の代わりに使う simulated driver adapter

Simulation subsystem 固有の public / cross-package identifier は fibril_sim_* または fibril-sim-* を使います。 fibril_* は Fibril 全体または simulation 以外にも成立する component の名前として扱い、fibril_viewer、fibril_ros_frame__* のように sim を省略して simulation 固有の意味を Fibril 全体へ広げる命名は行いません。

Core dependency guard の役割

fibril_sim_core、fibril_sim_mujoco、fibril_sim_runtime、fibril_sim_models は ROS 2、pluginlib、ament-index integration API に依存させません。 fibril_sim_core、fibril_sim_mujoco、fibril_sim_runtime が reusable runtime、fibril_sim_models が reusable-model layer です。

fibril_sim_models は fibril_sim_mujoco の public runtime contract を利用できますが、fibril_sim_mujoco は fibril_sim_models に依存させません。 この境界には semantic dependency も含みます。 runtime は model plugin の具体名を見て actuator command semantics を決めず、plugin-backed actuator を generic PluginDefined として公開します。 model plugin 固有の attribute calibration も named plugin instance + attribute の generic MuJoCo overlay target で表現します。 これにより runtime が tire、attachment、motor、sensor など具体的な model catalog を知る構造を防ぎます。

resource lookup を core に入れると model identity と filesystem layout が ament environment に依存します。 pluginlib を core に入れると reusable runtime が plugin mechanism の lifecycle に依存します。 ROS を runtime に入れると active-state ownership が executor callback model と結び付きます。

ament/pluginlib integration は fibril_sim_ament、ROS integration は fibril_sim_ros の adapter boundary で接続します。 standard ROS composition root は Plan 構築を fibril_sim_ament に委譲し、SimulationRuntime に構築済み Plan を渡します。 これにより FibrilSimulationNode は ROS parameter、/clock、ROS frontend、service/topic 変換に責務を限定し、runtime 側へ rclcpp lifecycle を持ち込みません。 compatible simulated driver、viewer、recorder などの simulation-side client は、同一 process / 別 process を問わず fibril_sim_runtime::SimulationConnection を使用します。 MCU や production driver の実 bus interface を再現する場合は、Fibril Simulation IPC の先に SocketCAN、PTY などを置きます。

compatible_sim/* は production-facing ROS API を維持した hardware-driver-compatible adapter 群です。 これらは SimulationConnection を Fibril 側の境界として使い、active SimulationHost や MuJoCo state を直接参照しません。

fibril_sim_models は built-in profile catalog の logical resource name を定義できますが、ament index から package share path を検索しません。 filesystem path は headless caller が明示し、ROS 2 integration では fibril_sim_ament が MuJoCo の package:// ResourceProvider を登録した後に同じ logical URI を使用します。 このため Component profile catalog、physical-model profile、MJCF preset は package resource として配布しつつ、model library 自体を ament lookup へ依存させません。

profile の ownership は model と同じ基準で決めます。 複数 robot で同じ意味を持つ device nominal property、material/surface interaction、generic mechanism preset は fibril_sim_models に置き、特定 robot の mounting offset、個体補正、installed-system effective parameter、task threshold は consumer 側に置きます。

Optional dependency の扱い

rendering は fibril_sim_render に隔離します。 core camera と test fixture が EGL/OpenGL を要求しないため、headless CI に graphics dependency を強制しません。

calibration も SimulationInstance lifecycle を再利用する上位 package です。 optimizer を core runtime の責務へ取り込みません。 calibration package は request parsing と fit orchestration を所有しますが、standard component catalog や ament-backed Plan の選択は所有しません。 fibril_sim_cli は private composition として standard model decoder と candidate Plan builder を接続し、その generic calibration API を呼びます。

fibril_sim_cli は install/export される C++ library API を持ちません。 CLI を外して別 frontend を作る場合に再実装したくなる selector、schema、experiment runner、generic calibration execution は CLI package の外に置きます。