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
tests/unit/cargo-delivery.test.tsadded+219-0
Changes to tests/unit/cargo-delivery.test.ts
@@ -0,0 +1,219 @@
1import { expect, test } from 'bun:test'
2import { cargoDeliverySummary, simulateCargoDelivery } from '../../resources/functions/drone/cargo/delivery'
3import { replayVehicleMission, validateVehicleMission } from '../../resources/functions/drone/missions/vehicle'
4
5// Public delivery simulation: actual mass/CG plant, raw navigation, commanded
6// mechanism, delayed model observations and mission replay. No physical IO.
7test('a simulated parcel is released and received before the carrier returns and lands', () => {
8 const result = simulateCargoDelivery()
9 expect(result.evidence).toBe('owned-cargo-delivery-simulation')
10 expect(result.status).toBe('completed')
11 expect(result.delivery.outcome).toBe('received')
12 expect(result.initialLoad.properties.totalMassKg).toBe(1.6)
13 expect(result.finalLoad.properties.totalMassKg).toBe(1.5)
14 expect(result.release?.outcome).toBe('separated')
15 expect(result.delivery.mechanismCapturedAtMs).toBeGreaterThan(result.delivery.requestedAtMs!)
16 expect(result.delivery.receiptCapturedAtMs).toBeGreaterThan(result.delivery.mechanismCapturedAtMs!)
17 expect(result.parcel?.onSurface).toBe(true)
18 expect(result.runtime.mission.state).toBe('completed')
19 expect(replayVehicleMission(result.runtime.trace).snapshot()).toEqual(result.runtime.mission)
20 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
21 expect(result.physicalFlightEnabled).toBe(false)
22 expect(result.identityAuthenticated).toBe(false)
23}, 30000)
24
25test('mechanism and receiver observations retain the executed command after its acknowledgement', () => {
26 const result = simulateCargoDelivery()
27 const request = result.runtime.trace.rows.find(row => row.result.payload !== null)!.result.payload!
28 const later = result.runtime.path.filter(row => row.atMs > result.delivery.acknowledgedAtMs! + 100)
29 expect(later.length).toBeGreaterThan(10)
30 for (const row of later) {
31 expect(row.measurement?.values.mechanismEventId).toBe(request.eventId)
32 expect(row.measurement?.values.receiptEventId).toBe(request.eventId)
33 expect(row.measurement?.values.loadAttached).toBe(false)
34 }
35}, 30000)
36
37for (const scenario of ['recipient-absent', 'site-blocked']) {
38 test('a delivery cannot release without current ' + scenario + ' evidence', () => {
39 const result = simulateCargoDelivery({ scenario })
40 expect(result.status).toBe('diverted')
41 expect(result.delivery.outcome).toBe('not-released')
42 expect(result.delivery.reason).toBe('release-evidence-unqualified')
43 expect(result.release).toBeNull()
44 expect(result.finalLoad.properties.totalMassKg).toBe(1.6)
45 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
46 expect(result.runtime.mission.reason).toBe('payload-diversion-landed')
47 }, 30000)
48}
49
50test('a captured mechanism jam refuses delivery without separating the actual carried mass', () => {
51 const result = simulateCargoDelivery({ scenario: 'mechanism-jam' })
52 expect(result.status).toBe('diverted')
53 expect(result.delivery.outcome).toBe('not-released')
54 expect(result.delivery.reason).toBe('mechanism-jammed')
55 expect(result.release).toBeNull()
56 expect(result.finalLoad.properties.totalMassKg).toBe(1.6)
57 const acknowledgements = result.runtime.trace.rows.flatMap(row => row.observation.payloadAck ? [row.observation.payloadAck] : [])
58 expect(acknowledgements).toHaveLength(1)
59 expect(acknowledgements[0]!.outcome).toBe('rejected')
60 expect(acknowledgements[0]!.capturedAtMs).toBe(result.delivery.mechanismCapturedAtMs!)
61 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
62}, 30000)
63
64for (const scenario of ['receipt-loss', 'foreign-receipt']) {
65 test('a separated parcel remains uncertain under ' + scenario, () => {
66 const result = simulateCargoDelivery({ scenario })
67 expect(result.status).toBe('diverted')
68 expect(result.release?.outcome).toBe('separated')
69 expect(result.finalLoad.properties.totalMassKg).toBe(1.5)
70 expect(result.delivery.mechanismOutcome).toBe('open')
71 expect(result.delivery.outcome).toBe('uncertain')
72 expect(result.delivery.receiptCapturedAtMs).toBeNull()
73 expect(result.runtime.mission.reason).toBe('payload-diversion-landed')
74 expect(result.runtime.trace.rows.some(row => row.result.reason === 'payload-confirmed')).toBe(false)
75 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
76 }, 30000)
77}
78
79
80test('a refused release takes only the declared finite alternate and lands without claiming delivery', () => {
81 const result = simulateCargoDelivery({ scenario: 'site-blocked' })
82 expect(result.status).toBe('diverted')
83 expect(result.delivery.outcome).toBe('not-released')
84 expect(result.runtime.mission.state).toBe('completed')
85 expect(result.runtime.mission.payloadFailure?.taskId).toBe('release')
86 expect(result.runtime.mission.payloadFailure?.reason).toBe('rejected')
87 expect(result.runtime.mission.payloadFailure?.landingTaskId).toBe('alternate-land')
88 expect(result.runtime.trace.rows.at(-1)!.observation.onGround).toBe(true)
89 expect(result.runtime.path.some(row => row.mission.taskId === 'home')).toBe(false)
90 expect(result.runtime.trace.rows.filter(row => row.result.payload !== null).map(row => row.result.payload!.eventId).every(id => id === result.runtime.mission.payloadFailure!.eventId)).toBe(true)
91 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
92 expect(replayVehicleMission(result.runtime.trace).snapshot()).toEqual(result.runtime.mission)
93}, 30000)
94
95
96test('declared reserve planning includes the entire alternate route before execution', () => {
97 const plan = simulateCargoDelivery().runtime.trace.plan
98 const approach = plan.tasks.find(task => task.id === 'alternate-approach')!
99 const land = plan.tasks.find(task => task.id === 'alternate-land')!
100 Object.assign(approach, { timeoutMs: 60000 })
101 Object.assign(land, { timeoutMs: 60000 })
102 const budget = validateVehicleMission(plan)
103 // 20 ms start + 20 s takeoff + 20 s site + 1.5 s release + two 60 s alternate tasks.
104 expect(budget.worstCaseMs).toBe(161520)
105 expect(budget.requiredWh).toBe(26.92)
106 plan.power.availableWh = 30
107 // Normal return fits 21 Wh usable, while the declared failure path does not.
108 expect(() => validateVehicleMission(plan)).toThrow('Vehicle mission cannot preserve energy reserve')
109}, 30000)
110
111test('a payload failure route cannot request another release or move its declared landing site', () => {
112 const plan = simulateCargoDelivery().runtime.trace.plan
113 const releaseAgain = structuredClone(plan)
114 releaseAgain.tasks[releaseAgain.tasks.findIndex(task => task.id === 'alternate-approach')] = { id: 'alternate-approach', kind: 'payload', operation: 'material-drop', containerId: 'another-parcel', timeoutMs: 1000, next: 'alternate-land' }
115 expect(() => validateVehicleMission(releaseAgain)).toThrow('Invalid vehicle mission')
116 const wrongSite = structuredClone(plan), land = wrongSite.tasks.find(task => task.id === 'alternate-land')!
117 if (land.kind !== 'land') throw new Error('Expected declared landing')
118 land.positionM[0] = 2
119 expect(() => validateVehicleMission(wrongSite)).toThrow('Invalid vehicle mission')
120}, 30000)
121
122test('delivery acknowledgement positions belong to the captured receiver packet epoch', () => {
123 const result = simulateCargoDelivery()
124 const row = result.runtime.trace.rows.find(row => row.observation.payloadAck !== null)!
125 const ack = row.observation.payloadAck!
126 const received = result.runtime.path.find(path => path.atMs === row.observation.nowMs)!
127 expect(received.measurement!.capturedAtMs).toBe(ack.capturedAtMs)
128 expect(received.measurementPose!.capturedAtMs).toBe(ack.capturedAtMs)
129 expect(ack.positionM).toEqual(received.measurementPose!.positionM)
130 expect(received.atMs - ack.capturedAtMs).toBe(40)
131}, 30000)
132
133test('a delivery continues on its captured backup link without changing vehicle authority or custody', () => {
134 const result = simulateCargoDelivery({ scenario: 'primary-link-loss' })
135 expect(result.status).toBe('completed')
136 expect(result.delivery.outcome).toBe('received')
137 const failover = result.linkEvents.find(event => event.selectedSource === 'backup')!
138 expect(failover).toBeDefined()
139 expect(failover.observedAtMs).toBeGreaterThan(5000)
140 expect(failover.authority.capturedAtMs).toBeLessThan(failover.observedAtMs)
141 expect(failover.sources.find(source => source.sourceId === 'primary')!.capturedAtMs).toBe(4980)
142 expect(result.links.selectedSource).toBe('backup')
143 expect(result.links.latchedLoss).toBe(false)
144 expect(result.links.scope).toEqual({ vehicleId: 'carrier-a', bootId: 55, sessionId: 123 })
145 expect(result.runtime.authority.bootId).toBe(55n)
146 expect(result.runtime.authority.sessionId).toBe(123n)
147 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
148}, 30000)
149
150test('loss of both delivery links latches loss and revokes the carrier before release', () => {
151 const result = simulateCargoDelivery({ scenario: 'both-links-loss' })
152 expect(result.status).toBe('blocked')
153 expect(result.links.latchedLoss).toBe(true)
154 expect(result.links.authority.connected).toBe(false)
155 expect(result.delivery.outcome).toBe('not-released')
156 expect(result.release).toBeNull()
157 expect(result.runtime.mission.state).not.toBe('completed')
158 expect(result.runtime.authority.events.some(event => event.reason === 'link-loss')).toBe(true)
159 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
160 expect(result.runtime.board.expiresAtMs).toBeNull()
161 expect(replayVehicleMission(result.runtime.trace).snapshot()).toEqual(result.runtime.mission)
162}, 30000)
163
164test('degraded delivery navigation revokes authority without releasing the parcel', () => {
165 const result = simulateCargoDelivery({ scenario: 'position-loss' })
166 expect(result.status).toBe('blocked')
167 expect(result.delivery.outcome).toBe('not-released')
168 expect(result.release).toBeNull()
169 expect(result.runtime.authority.events.some(event => ['estimator-loss', 'stale-estimator'].includes(event.reason))).toBe(true)
170 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
171 expect(result.runtime.board.expiresAtMs).toBeNull()
172}, 30000)
173
174for (const scenario of ['imu-loss', 'vehicle-sensor-loss', 'rc-override', 'kill', 'host-loss']) {
175 test('delivery retains cargo and neutral output under ' + scenario, () => {
176 const result = simulateCargoDelivery({ scenario })
177 expect(result.status).toBe(scenario === 'host-loss' ? 'host-lost' : 'blocked')
178 expect(result.delivery.outcome).toBe('not-released')
179 expect(result.release).toBeNull()
180 expect(result.runtime.mission.state).not.toBe('completed')
181 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
182 expect(result.runtime.board.expiresAtMs).toBeNull()
183 expect(cargoDeliverySummary(result).demonstrationMatched).toBe(true)
184 if (scenario === 'host-loss') {
185 expect(result.runtime.board.fault).toBe('output-lease-expired')
186 expect(result.runtime.authority.state).toBe('autonomous')
187 }
188 if (scenario === 'rc-override') expect(result.runtime.authority.events.some(event => event.to === 'manual')).toBe(true)
189 if (scenario === 'kill') expect(result.runtime.authority.events.some(event => event.to === 'killed')).toBe(true)
190 }, 30000)
191}
192
193test('a delivery target outside the independent authority fence cannot escape containment', () => {
194 const result = simulateCargoDelivery({ scenario: 'authority-containment' })
195 expect(result.status).toBe('blocked')
196 expect(result.release).toBeNull()
197 expect(result.delivery.outcome).toBe('not-released')
198 expect(result.runtime.authority.events.some(event => event.reason === 'invalid-target-or-lease')).toBe(true)
199 expect(result.runtime.path.every(row => Math.hypot(row.truthPositionM[0], row.truthPositionM[1]) <= 2)).toBe(true)
200 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
201}, 30000)
202
203for (const scenario of ['diversion-position-loss', 'diversion-kill']) {
204 test('an alternate route cannot override ' + scenario, () => {
205 const result = simulateCargoDelivery({ scenario })
206 expect(result.status).toBe('blocked')
207 expect(result.runtime.mission.payloadFailure?.reason).toBe('rejected')
208 expect(result.runtime.mission.state).not.toBe('completed')
209 expect(result.delivery.outcome).toBe('not-released')
210 expect(result.release).toBeNull()
211 const failureAtMs = result.runtime.mission.payloadFailure!.triggeredAtMs
212 expect(result.runtime.path.some(row => row.atMs > failureAtMs && row.atMs < failureAtMs + 200 && row.mission.taskId === 'alternate-approach' && row.actuators.some(n => n > 0))).toBe(true)
213 expect(result.runtime.board.actuators).toEqual([0, 0, 0, 0])
214 expect(result.runtime.board.expiresAtMs).toBeNull()
215 if (scenario === 'diversion-kill') expect(result.runtime.authority.state).toBe('killed')
216 else expect(result.runtime.authority.events.some(event => ['estimator-loss', 'stale-estimator'].includes(event.reason))).toBe(true)
217 expect(replayVehicleMission(result.runtime.trace).snapshot()).toEqual(result.runtime.mission)
218 }, 30000)
219}