svc-core/docs/GUIDELINES.md

---
type: guidelines
---
# Core services guidelines

## 1. One writer: `obd-poller`, and never on CAN
- `obd-poller` is the only thing that sends anything to the car (project-yukart
  decisions 3 and 30): OBD-II requests, one at a time, on the K-line through the
  Bluetooth ELM327, with the ELM's protocol fixed so it never probes CAN.  
- Nothing in svc-core transmits on CAN. The recorder and the decoder only read;
  anything else that writes to `can_pcan` is a bug.  
- `can_pcan` still acknowledges frames like any scan tool (listen-only off since
  2026-10-12, left so as harmless). Going back is one line in orin-nano-env-setup's
  `/etc/default/can-can_pcan`.

## 2. Capture never waits
- A frame missed is gone. Producers hand frames to the writer without blocking;
  what doesn't fit is **counted**, recorded as an event, and never silently lost.  
- Capture reads SocketCAN and gpsd directly. It does not depend on the broker, a
  display, or any other service being up.

## 3. Every failure leaves complete files
- Append, flush and `fdatasync` about once a second. Power loss costs at most the
  last second.  
- Replace files by write-temp, fsync, rename. Never rewrite in place.  
- Anything found half-done at startup is repaired or marked, not deleted.

## 4. Raw stays raw
- Recordings are `candump -L` text plus the gpsd JSON as received, so `can-utils`,
  `canplayer` and anything already written against the first captures keep working.  
- Decoding happens downstream of the recording, never instead of it.

## 5. Time is evidence, not truth
- The car unit's clock can boot stale and be stepped mid-drive. Record what is
  needed to correct it later (sync state, monotonic time, observed steps, GNSS
  time beside local receive time) rather than trusting it.

## 6. To be added