tool-mock/docs/GUIDELINES.md

---
type: guidelines
---
# Mock and fixture guidelines

## 1. Fixtures publish the real contract
- A fixture emits the **real topic with the real payload schema**. `yukart/gnss/fix`
  from a replayed track must be indistinguishable, at the bus, from a real fix.  
- ⚠ **A fixture that invents its own topic or shape defers integration rather than
  removing it** — the mismatch surfaces when the real source arrives, which is the
  moment it is most expensive.

## 2. Do not reimplement our own services
- Stub the **car** and the **hardware**. Never write a *separate* implementation of
  `svc-gw`, `svc-nav` or anything else we wrote — a second implementation of our own
  contract will drift from the first.  
- A service mocking **itself**, behind its own input interface, is the right shape:
  one codebase, one contract implementation, a swappable data source. That belongs
  in the service's own repo, not here.  
- None of our services touch hardware, so they all run on x86 unmodified either way.

## 3. Prefer upstream tools, wrap rather than rewrite
- `vcan`, `canplayer` and ICSim already solve the CAN problem. This repo holds the
  scripts that drive them, not reimplementations of them.

## 4. Recorded logs are data, not source
- `candump` logs and GPX tracks are artifacts. Reference them, do not commit them.

## 5. To be added