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