ReviewOS

also looking at this

stacks/drone

feat: add shared-clock scoped vehicle simulation sessions

#98
Merged chris wants to merge codex/cargo-fleet-runtime into main
42 files +2764 -127
docs/adr/0035-shared-clock-vehicle-sessions.mdadded+42-0
Changes to docs/adr/0035-shared-clock-vehicle-sessions.md
@@ -0,0 +1,42 @@
1# ADR 0035: Retained vehicle sessions on one modeled clock
2
3Status: accepted for software simulation.
4
5## Context
6
7Cargo issue #25 needs distinct vehicles with current authority and source evidence at
8the handover epoch. Running one complete fixture and relabeling its result as a fresh
9peer would discard timing, independent watchdog and sensor identity requirements.
10The shared vehicle loop previously ran to completion with fixed boot 55/session 123.
11
12## Decision
13
14Expose `createVehicleSimulationSession` over that same loop. Its caller advances exact
154 ms epochs from zero; the loop retains raw sensing, estimator updates, 20 ms policy,
16mission, controls, authority, payload ownership and independent board state. The ordinary
17`runVehicleSimulation` drains this interface to the same terminal report.
18
19Capture an optional nonzero uint64 boot/session scope before allocating a profile session.
20The actual synthetic raw packets, pipeline clock anchor, estimator reference, supervisor
21and board use that scope. Defaults retain the original identities and report projection.
22Identity labels do not authenticate a peer, prevent duplicate scope selection or establish
23distributed time synchronization.
24
25Ticks expose detached mission/authority/board snapshots, reference, phase and last completed
26host policy epoch. Host loss freezes host work while the finite independent settling tail
27can still advance the board and plant. The caller can advance another live vehicle at the
28same epochs. Payload teardown occurs once. Explicit close or a step exception revokes the
29board and closes ownership; simultaneous failures remain observable.
30
31## Consequences
32
33This is a necessary runtime prerequisite for a captured, two-vehicle custody protocol.
34It does not implement that protocol or claim fleet handover is complete. The cargo
35coordinator must still bind distinct peers, physically modeled parcel transfer, current
36qualified captures, cancellation and conservative uncertain outcomes.
37
38The caller owns stepping and cleanup and must stop stepping a terminal session. Invalid
39epochs do not mutate execution. `result` is unavailable until terminal and detached
40thereafter. Explicit close stops simulation without running recovery or a physical
41settling interval. All physical outputs remain inhibited. This clock is deterministic
42simulation time, not a wall-clock deadline guarantee or real-time hardware scheduler.