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-coordinator.test.tsadded+279-0
Changes to tests/unit/cargo-delivery-coordinator.test.ts
@@ -0,0 +1,279 @@
1import { expect, test } from 'bun:test'
2import type { SensorVector } from '../../resources/functions/drone/sensors/types'
3import type { VehicleControllerContext, VehiclePayloadCommand } from '../../resources/functions/drone/vehicles/types'
4import { createCargoDeliveryCoordinator } from '../../resources/functions/drone/cargo/coordinator'
5import { vehicleReference } from '../../resources/functions/drone/vehicles/measurements'
6import { observation } from '../fixtures/authority/context'
7
8const declaration = { origin: { latitudeDeg: 0, longitudeDeg: 0, ellipsoidHeightM: 100 }, site: { id: 'receiver-west', recipientId: 'recipient-west', containerId: 'parcel-west', positionM: [2, -1, 0] as SensorVector, radiusM: .35 }, releaseHeightM: 1 }
9function context(nowMs: number, sequence: number): VehicleControllerContext {
10 const estimate = observation(nowMs).estimate
11 estimate.localPosition!.positionM = [2, -1, -1]
12 estimate.localPosition!.covarianceBlocks = [0, 1, 2].map(() => ({ positionM2: .0001, positionVelocityM2S: 0, velocityM2S2: .0001 }))
13 const reference = vehicleReference(estimate), capturedAtMs = nowMs - 40
14 return { nowMs, enabled: true, estimate,
15 measurement: { version: 1, evidence: 'modeled-vehicle-sensors', vehicle: 'quadcopter', sequence, reference, capturedAtMs, receivedAtMs: nowMs,
16 values: { onSurface: false, stopped: false, siteId: 'receiver-west', recipientId: 'recipient-west', siteClear: true, recipientPresent: true, loadAttached: true, mechanismOpen: false, mechanismJammed: false, mechanismEventId: '', receiptEventId: '', receiptContainerId: 'parcel-west' } },
17 measurementPose: { capturedAtMs, reference, positionM: [2, -1, -1], quaternionWxyz: [1, 0, 0, 0], positionCapturedAtMs: capturedAtMs, positionPredictedToMs: capturedAtMs, attitudeCapturedAtMs: capturedAtMs, attitudePredictedToMs: capturedAtMs, gyroCapturedAtMs: capturedAtMs, attitudePrediction: 'qualified-gyro-hold' },
18 controlRate: { evidence: 'modeled-qualified-imu', capturedAtMs: nowMs, reference, angularRateRadS: [0, 0, 0] },
19 mission: { version: 2, vehicle: 'quadcopter', evidence: 'owned-vehicle-mission-simulation', physicalFlightEnabled: false, state: 'running', taskId: 'release', taskKind: 'payload', targetM: [2, -1, -1], payload: null, reason: 'task-entered', elapsedMs: 0 } }
20}
21function command(c: VehicleControllerContext): VehiclePayloadCommand {
22 return { eventId: 'delivery-west:release', taskId: 'release', operation: 'material-drop', containerId: 'parcel-west', issuedAtMs: c.nowMs, expiresAtMs: c.nowMs + 1500, positionM: [2, -1, -1], reference: vehicleReference(c.estimate) }
23}
24
25// Public policy seam, with declared capture fixtures as transport observations.
26// Actual raw sensors/physics remain covered by the delivery runtime campaign.
27test('a caller-selected delivery site releases once and requires captured mechanism and recipient evidence', () => {
28 const sent: VehiclePayloadCommand[] = []
29 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(structuredClone(value)), cancel() {} })
30 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
31 const ready = context(1500, 26), request = command(ready)
32 ready.mission.payload = request; coordinator.port.observe!(ready); coordinator.port.request(request)
33 expect(sent).toEqual([request])
34 expect(coordinator.snapshot().delivery.outcome).toBe('uncertain')
35 expect(coordinator.port.poll(1500)).toBeNull()
36 const opened = context(1560, 29); opened.mission.payload = request
37 Object.assign(opened.measurement!.values, { loadAttached: false, mechanismOpen: true, mechanismEventId: request.eventId })
38 coordinator.port.observe!(opened)
39 expect(coordinator.port.poll(1560)).toBeNull()
40 expect(coordinator.snapshot().delivery.outcome).toBe('in-transit')
41 const received = context(1580, 30); received.mission.payload = request
42 Object.assign(received.measurement!.values, { loadAttached: false, mechanismOpen: true, mechanismEventId: request.eventId, receiptEventId: request.eventId })
43 coordinator.port.observe!(received)
44 expect(coordinator.port.poll(1580)).toMatchObject({ outcome: 'confirmed', capturedAtMs: 1540, positionM: [2, -1, -1], metadata: { expectedSiteId: 'receiver-west', expectedRecipientId: 'recipient-west' } })
45 expect(coordinator.snapshot().delivery).toMatchObject({ outcome: 'received', siteId: 'receiver-west', recipientId: 'recipient-west', mechanismCapturedAtMs: 1520, receiptCapturedAtMs: 1540 })
46 expect(coordinator.port.poll(1600)).toBeNull()
47 expect(() => coordinator.port.request(request)).toThrow('cargo-delivery-command-replayed')
48 expect(sent).toHaveLength(1)
49})
50
51test('an aging retained packet breaks readiness even when its sequence has not changed', () => {
52 const sent: VehiclePayloadCommand[] = []
53 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
54 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
55 const retained = context(1560, 26), previous = context(1500, 26)
56 retained.measurement = previous.measurement; retained.measurementPose = previous.measurementPose
57 coordinator.port.observe!(retained)
58 expect(coordinator.snapshot().readiness.distinctCaptures).toBe(0)
59 const fresh = context(1580, 27), request = command(fresh)
60 fresh.mission.payload = request; coordinator.port.observe!(fresh); coordinator.port.request(request)
61 expect(sent).toHaveLength(0)
62 expect(coordinator.snapshot().delivery).toMatchObject({ outcome: 'not-released', reason: 'release-evidence-unqualified' })
63})
64
65test('release readiness rejects gyro evidence from another estimator reference', () => {
66 const sent: VehiclePayloadCommand[] = []
67 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
68 for (let i = 0; i <= 25; i++) {
69 const c = context(1000 + i * 20, i + 1); c.controlRate!.reference = 'another-reference'
70 coordinator.port.observe!(c)
71 }
72 const c = context(1500, 26), request = command(c); c.controlRate!.reference = 'another-reference'; c.mission.payload = request
73 coordinator.port.observe!(c); coordinator.port.request(request)
74 expect(sent).toHaveLength(0)
75 expect(coordinator.snapshot().delivery.reason).toBe('release-evidence-unqualified')
76})
77
78test('retiming a packet with an unchanged sequence cannot preserve a release window', () => {
79 const sent: VehiclePayloadCommand[] = []
80 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
81 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
82 const retimed = context(1540, 26), request = command(retimed)
83 retimed.mission.payload = request; coordinator.port.observe!(retimed); coordinator.port.request(request)
84 expect(sent).toHaveLength(0)
85 expect(coordinator.snapshot().readiness.distinctCaptures).toBe(0)
86})
87
88test('a fresh packet after an unobserved scheduling gap must rebuild the readiness window', () => {
89 const sent: VehiclePayloadCommand[] = []
90 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
91 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
92 const afterGap = context(1660, 27), request = command(afterGap)
93 afterGap.mission.payload = request; coordinator.port.observe!(afterGap); coordinator.port.request(request)
94 expect(sent).toHaveLength(0)
95 expect(coordinator.snapshot().readiness).toMatchObject({ distinctCaptures: 1, sinceMs: 1660 })
96})
97
98test('a receiver claim cannot turn captured jammed and attached cargo into received custody', () => {
99 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request() {}, cancel() {} })
100 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
101 const c = context(1500, 26), request = command(c); c.mission.payload = request
102 coordinator.port.observe!(c); coordinator.port.request(request)
103 const contradictory = context(1560, 29); contradictory.mission.payload = request
104 Object.assign(contradictory.measurement!.values, { mechanismEventId: request.eventId, mechanismJammed: true, receiptEventId: request.eventId })
105 coordinator.port.observe!(contradictory)
106 expect(coordinator.port.poll(1560)?.outcome).not.toBe('confirmed')
107 expect(coordinator.snapshot().delivery.outcome).not.toBe('received')
108 expect(coordinator.snapshot().delivery.receiptCapturedAtMs).toBeNull()
109})
110
111test('ambient mechanism and receipt fields cannot confirm a release that the policy refused to dispatch', () => {
112 const sent: VehiclePayloadCommand[] = []
113 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
114 const unready = context(1500, 1), request = command(unready); unready.mission.payload = request
115 coordinator.port.observe!(unready); coordinator.port.request(request)
116 expect(sent).toHaveLength(0)
117 const claimed = context(1560, 2); claimed.mission.payload = request
118 Object.assign(claimed.measurement!.values, { mechanismOpen: true, loadAttached: false, mechanismEventId: request.eventId, receiptEventId: request.eventId })
119 coordinator.port.observe!(claimed)
120 expect(coordinator.port.poll(1560)?.outcome).toBe('rejected')
121 expect(coordinator.snapshot().delivery).toMatchObject({ outcome: 'not-released', mechanismCapturedAtMs: null, receiptCapturedAtMs: null, reason: 'release-evidence-unqualified' })
122})
123
124const invalidEstimates: [string, (c: VehicleControllerContext) => void][] = [
125 ['zero attitude quaternion', c => { c.estimate.attitude!.quaternionWxyz = [0, 0, 0, 0] }],
126 ['non-unit attitude quaternion', c => { c.estimate.attitude!.quaternionWxyz = [2, 0, 0, 0] }],
127 ['future position capture', c => { c.estimate.localPosition!.capturedAtMs = c.nowMs + 1 }],
128 ['stale position capture', c => { c.estimate.localPosition!.capturedAtMs = c.nowMs - 201 }],
129 ['unpredicted position', c => { c.estimate.localPosition!.predictedToMs = c.nowMs - 20 }],
130 ['wrong estimator time', c => { c.estimate.nowMs = c.nowMs - 20 }],
131 ['negative velocity variance', c => { c.estimate.localPosition!.covarianceBlocks[0]!.velocityM2S2 = -1 }],
132 ['indefinite covariance', c => { c.estimate.localPosition!.covarianceBlocks[0]!.positionVelocityM2S = 1 }],
133]
134for (const [label, corrupt] of invalidEstimates) test(`release readiness refuses ${label}`, () => {
135 const sent: VehiclePayloadCommand[] = []
136 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
137 for (let i = 0; i <= 25; i++) { const c = context(1000 + i * 20, i + 1); corrupt(c); coordinator.port.observe!(c) }
138 const c = context(1500, 26), request = command(c); corrupt(c); c.mission.payload = request
139 coordinator.port.observe!(c); coordinator.port.request(request)
140 expect(sent).toHaveLength(0)
141 expect(coordinator.snapshot().delivery.reason).toBe('release-evidence-unqualified')
142})
143
144const invalidCommands: [string, (request: VehiclePayloadCommand) => void][] = [
145 ['another task', request => { request.taskId = 'another-task' }],
146 ['a different issue-time position', request => { request.positionM = [100, 0, -1] }],
147 ['an unbounded lease', request => { request.expiresAtMs = Infinity }],
148 ['a lease beyond the native task ceiling', request => { request.expiresAtMs += 10000 }],
149 ['a fractional deadline', request => { request.expiresAtMs += .5 }],
150 ['an empty event', request => { request.eventId = '' }],
151]
152for (const [label, corrupt] of invalidCommands) test(`release request refuses ${label}`, () => {
153 const sent: VehiclePayloadCommand[] = []
154 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
155 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
156 const c = context(1500, 26), request = command(c); corrupt(request); c.mission.payload = request
157 coordinator.port.observe!(c); coordinator.port.request(request)
158 expect(sent).toHaveLength(0)
159 expect(coordinator.snapshot().delivery.reason).toBe('release-evidence-unqualified')
160})
161
162test('a throwing mechanism retains dispatch uncertainty and is cancelled once without a release retry', () => {
163 const sent: VehiclePayloadCommand[] = [], cancelled: string[] = []
164 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request(value) { sent.push(value); throw new Error('private adapter detail') }, cancel: eventId => { cancelled.push(eventId) } })
165 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
166 const c = context(1500, 26), request = command(c); c.mission.payload = request
167 coordinator.port.observe!(c); coordinator.port.request(request)
168 expect(coordinator.snapshot().delivery).toMatchObject({ outcome: 'uncertain', reason: 'mechanism-transport-unavailable' })
169 coordinator.port.close(); coordinator.port.close()
170 expect(sent).toHaveLength(1)
171 expect(cancelled).toEqual([request.eventId])
172 expect(coordinator.snapshot().delivery.outcome).toBe('uncertain')
173 expect(() => coordinator.port.request(request)).toThrow('cargo-delivery-command-replayed')
174})
175
176test('a captured receipt cannot silently clear a mechanism dispatch failure', () => {
177 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request() { throw new Error('private transport detail') }, cancel() {} })
178 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
179 const c = context(1500, 26), request = command(c); c.mission.payload = request
180 coordinator.port.observe!(c); coordinator.port.request(request)
181 const claimed = context(1560, 29); claimed.mission.payload = request
182 Object.assign(claimed.measurement!.values, { mechanismOpen: true, loadAttached: false, mechanismEventId: request.eventId, receiptEventId: request.eventId })
183 coordinator.port.observe!(claimed)
184 expect(coordinator.port.poll(1560)?.outcome).toBe('uncertain')
185 expect(coordinator.snapshot().delivery).toMatchObject({ outcome: 'uncertain', receiptCapturedAtMs: null, reason: 'mechanism-transport-unavailable' })
186})
187
188test('loss of authority after dispatch preserves uncertain custody and cancels the pending mechanism', () => {
189 const cancelled: string[] = []
190 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request() {}, cancel: eventId => { cancelled.push(eventId) } })
191 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
192 const c = context(1500, 26), request = command(c); c.mission.payload = request
193 coordinator.port.observe!(c); coordinator.port.request(request)
194 const revoked = context(1520, 27); revoked.enabled = false; revoked.mission.payload = request
195 coordinator.port.observe!(revoked)
196 expect(coordinator.port.poll(1520)).toBeNull()
197 expect(cancelled).toEqual([request.eventId])
198 expect(coordinator.snapshot().delivery).toMatchObject({ outcome: 'uncertain', reason: 'receipt-not-confirmed', receiptCapturedAtMs: null })
199})
200
201test('configuration and snapshots are detached and getter declarations never run', () => {
202 const input = structuredClone(declaration)
203 const coordinator = createCargoDeliveryCoordinator(input, { evidence: 'modeled-cargo-mechanism', request() {}, cancel() {} })
204 input.site.id = 'mutated-site'; input.site.positionM[0] = 900
205 const snapshot = coordinator.snapshot(); snapshot.declaration.site.positionM[0] = 800; snapshot.delivery.outcome = 'received'
206 expect(coordinator.snapshot().declaration).toEqual(declaration)
207 expect(coordinator.snapshot().delivery.outcome).toBe('not-released')
208 let reads = 0
209 const getter = { ...declaration, get releaseHeightM() { reads++; return 1 } }
210 expect(() => createCargoDeliveryCoordinator(getter, { evidence: 'modeled-cargo-mechanism', request() {}, cancel() {} })).toThrow('cargo-delivery-declaration')
211 expect(reads).toBe(0)
212 expect(() => createCargoDeliveryCoordinator({ ...declaration, extra: true }, { evidence: 'modeled-cargo-mechanism', request() {}, cancel() {} })).toThrow('cargo-delivery-declaration')
213})
214
215test('terminal uncertainty cancels a possibly queued release before clearing the event', () => {
216 let queued: VehiclePayloadCommand | null = null
217 const cancelled: string[] = []
218 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request(value) { queued = value; throw new Error('queued before failure') }, cancel(eventId) { cancelled.push(eventId); if (queued?.eventId === eventId) queued = null } })
219 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
220 const c = context(1500, 26), request = command(c); c.mission.payload = request
221 coordinator.port.observe!(c); coordinator.port.request(request)
222 const fresh = context(1560, 29); fresh.mission.payload = request
223 coordinator.port.observe!(fresh)
224 expect(coordinator.port.poll(1560)?.outcome).toBe('uncertain')
225 expect(queued).toBeNull()
226 const revoked = context(1580, 30); revoked.enabled = false
227 coordinator.port.observe!(revoked); coordinator.port.close()
228 expect(cancelled).toEqual([request.eventId])
229 expect(coordinator.snapshot().delivery.outcome).toBe('uncertain')
230})
231
232test('receipt admission refuses a non-finite captured ACK position', () => {
233 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request() {}, cancel() {} })
234 for (let i = 0; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1))
235 const c = context(1500, 26), request = command(c); c.mission.payload = request
236 coordinator.port.observe!(c); coordinator.port.request(request)
237 const claimed = context(1560, 29); claimed.mission.payload = request; claimed.measurementPose!.positionM = [NaN, 0, -1]
238 Object.assign(claimed.measurement!.values, { mechanismOpen: true, loadAttached: false, mechanismEventId: request.eventId, receiptEventId: request.eventId })
239 coordinator.port.observe!(claimed)
240 expect(coordinator.port.poll(1560)).toBeNull()
241 expect(coordinator.snapshot().delivery.receiptCapturedAtMs).toBeNull()
242 expect(coordinator.snapshot().delivery.outcome).not.toBe('received')
243})
244
245test('variable transport lag cannot shorten the required source-capture readiness interval', () => {
246 const sent: VehiclePayloadCommand[] = []
247 const coordinator = createCargoDeliveryCoordinator(declaration, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
248 let last = context(1000, 1)
249 for (let i = 0; i <= 25; i++) {
250 last = context(1000 + i * 20, i + 1)
251 last.measurement!.capturedAtMs = last.nowMs - 20 - i * 2
252 coordinator.port.observe!(last)
253 }
254 // 26 fresh captures span only450ms even though receipt observations span500ms.
255 const request = command(last); last.mission.payload = request
256 coordinator.port.observe!(last); coordinator.port.request(request)
257 expect(sent).toHaveLength(0)
258 expect(coordinator.snapshot().delivery.reason).toBe('release-evidence-unqualified')
259})
260
261test('a declared non-default origin, elevated site and release height use their own metric geometry', () => {
262 const selected = { origin: { latitudeDeg: 50, longitudeDeg: 8, ellipsoidHeightM: 500 }, site: { id: 'receiver-north', recipientId: 'recipient-north', containerId: 'parcel-north', positionM: [4, 3, 2] as SensorVector, radiusM: .4 }, releaseHeightM: .6 }
263 const sent: VehiclePayloadCommand[] = []
264 const coordinator = createCargoDeliveryCoordinator(selected, { evidence: 'modeled-cargo-mechanism', request: value => sent.push(value), cancel() {} })
265 function selectedContext(nowMs: number, sequence: number) {
266 const c = context(nowMs, sequence)
267 c.estimate.localPosition!.origin = { ...selected.origin }; c.estimate.localPosition!.positionM = [4, 3, 1.4]
268 Object.assign(c.measurement!.values, { siteId: selected.site.id, recipientId: selected.site.recipientId, receiptContainerId: selected.site.containerId })
269 c.measurementPose!.positionM = [4, 3, 1.4]; c.mission.targetM = [4, 3, 1.4]
270 return c
271 }
272 for (let i = 0; i <= 25; i++) coordinator.port.observe!(selectedContext(1000 + i * 20, i + 1))
273 const c = selectedContext(1500, 26), request = command(c)
274 request.positionM = [4, 3, 1.4]; request.containerId = selected.site.containerId; c.mission.payload = request
275 coordinator.port.observe!(c); coordinator.port.request(request)
276 expect(sent).toEqual([request])
277 expect(coordinator.snapshot().declaration).toEqual(selected)
278 expect(coordinator.snapshot().delivery).toMatchObject({ outcome: 'uncertain', siteId: 'receiver-north', recipientId: 'recipient-north', containerId: 'parcel-north' })
279})