# 依赖分层与 Trait 边界

`config/dependency-policy.toml` 是依赖规则的唯一机器可读来源。crate 名称保持不变，manifest 按 `crates/<layer>/<domain>` 组织，并在 `[package.metadata.sentry-chassis]` 中声明 `layer`。

## 单向分层

```text
contract       can/imu
protocol       imu/motor/remote
transport      can/serial
device         imu/motor/esc/remote
control        algorithm/chassis/motor
experiment     trace
model          motor
simulation     motor
tooling        tuning
config         chassis
application    bench/daemon/tools/tuning
verification   integration
```

依赖只能从高层指向低层；正常依赖和 dev 依赖都必须如此。跨层集成测试集中在 `verification/integration`，不允许测试回边渗入低层 crate。

## Trait 组织

- `protocol/motor`：`MotorProtocol`、`EffortScale`、`FeedbackFields`，只处理线上的命令、反馈、帧 ID 和量程。
- `device/motor`：`MotorSpec`、`MotorFeedback`、`EffortDrive`、`VelocityDrive`、`PositionDrive`、`Disable`，只处理机械型号和设备能力。
- `device/esc`：`EscConfig<S>`、`EscMotor<S>`、`EscBus<S>` 通过 `MotorSpec::Protocol` 组合协议能力；电流路径要求 `CurrentEscDrive`，GM6020 使用独立的 `VoltageEscDrive` 路径。
- `model/motor`：`MotorPlant`、`DcMotorPlant<S>`，只处理动态模型和反馈量化。

`Gm3508`、`M2006`、`Gm6020` 是 marker type；型号事实、协议族和控制能力由关联类型组合，不在 bus 内用运行时 `match` 判断。

## 外部库边界

外部依赖必须从根 `workspace.dependencies` 继承，并在 policy 的 `external_roles` 中声明用途。异步/传输库只进入 transport/device；配置和 CLI 库只进入 config/application；搜索、并行、绘图库只进入 tuning/application；`approx`、`proptest` 只允许作为测试依赖。

## 审查脚本

`scripts/audit-rules.rs` 是单文件 Rust `cargo-script`。脚本通过内嵌 manifest 声明
`serde`、`serde_json`、`toml` 和 `regex`，不需要额外 Python 工具链。运行时使用
Nightly 的 `-Zscript`；workspace 本身仍由 `rust-toolchain.toml` 固定 Stable。

```sh
cargo +nightly -Zscript scripts/audit-rules.rs
cargo +nightly -Zscript scripts/audit-rules.rs --self-test
```

## 变更流程

新增 crate、内部边或外部库时，必须同步更新 `config/dependency-policy.toml`、crate 的 layer 声明、架构文档和 `Cargo.lock`。运行 `just audit`，提交时由 `.githooks/pre-commit` 执行同一规则。