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/vehicles.mdmodified+61-0
Changes to docs/vehicles.md
@@ -33,6 +33,67 @@ arming/engagement. Independent board leases expire to each declared neutral, inc
3333and air spring/wheel brake channels. Neutral does not imply a vehicle has physically stopped.
3434Host loss leaves a stale host mission snapshot; the independently ticking board still expires output.
3535
36## Shared-clock modeled sessions
37
38`createVehicleSimulationSession(profile, options)` in `vehicles/runtime.ts` retains the same
39owned loop behind `step(atMs)`, `result()` and `close()`. Start at zero and advance exactly
404 ms per call. Two sessions can therefore be advanced at each shared epoch before the
41coordinator evaluates their observations. Rejected duplicate, skipped or invalid epochs
42do not advance the session; a caller can supply the expected epoch afterward.
43
44An optional `scope: { bootId, sessionId }` captures two nonzero unsigned 64-bit bigints
45before session resources open. The boot identity is encoded in the actual synthetic IMU/GNSS
46packets, sensor clock anchor and estimator reference. Both identifiers also scope the
47authority supervisor and independent board. They are correlations, not authentication.
48Omitting scope preserves the original boot 55/session 123 reports.
49
50```ts
51const a = createVehicleSimulationSession(profileA, {
52 seconds: 120, scope: { bootId: 101n, sessionId: 201n },
53})
54const b = createVehicleSimulationSession(profileB, {
55 seconds: 120, scope: { bootId: 102n, sessionId: 202n },
56})
57try {
58 // Advance each live session once at every epoch; stop stepping one after terminal.
59 for (let atMs = 0, doneA = false, doneB = false; !doneA || !doneB; atMs += 4) {
60 if (!doneA) doneA = a.step(atMs).terminal
61 if (!doneB) doneB = b.step(atMs).terminal
62 }
63 console.log(a.result().status, b.result().status)
64}
65finally { a.close(); b.close() }
66```
67
68A tick returns detached mission, authority and board snapshots, the estimator reference,
69its actual epoch, phase, terminal flag and last completed host policy epoch. Policy still
70runs every 20 ms after alignment. During host loss or an opt-in independent settling tail,
71`policyAtMs` does not advance. Tail epochs run only board/plant work. Host authority and
72mission snapshots can remain stale; the board snapshot reflects its actual independent lease.
73
74`result()` refuses an active session and returns a detached terminal report. Explicit
75`close()` is idempotent: it closes owned payload state once, immediately revokes the modeled
76board and reports a blocked `simulation-session-closed` outcome. It does not invent mission
77completion, execute a recovery or settle the physical plant. A step failure also closes
78ownership and revokes output before throwing; a simultaneous cleanup failure is retained
79in an aggregate error. Naturally terminated sessions keep their existing terminal result.
80Closing from an adapter callback stops the in-flight step before another adapter or output
81acceptance runs. Recursive stepping is refused. An interrupted policy epoch is not reported
82as completed, and terminal sessions report `hostAvailable: false`.
83All adapter data results, including faults, plant state, navigation, measurements, payload
84acknowledgements and controller output, are captured inside that ownership check before use.
85A link callback that closes the session and then fails cannot hide the failure as a disconnected
86observation. Void observation/request callbacks keep their ignored-return contract.
87The initial plant snapshot and adapter method references are captured before the session
88is exposed. Replacing a method property afterward does not replace the retained adapter;
89modeled world changes belong in the adapter's own captured state.
90`runVehicleSimulation` now drains this same interface to natural termination.
91
92This enables concurrent modeled vehicle execution. It does not yet implement fleet custody
93transfer, collision avoidance, a network scheduler, distributed clocks or physical multi-vehicle
94control. Callers must avoid reusing identities. [Cargo issue #25](cargo-delivery.md#remaining-issue-scope)
95remains open for the actual handover policy and evidence.
96
3697## Payload and survey evidence
3798
3899Payload requests bind event, task, operation, container, reference, position and an expiry window.