ReviewOS

also looking at this

stacks/drone

feat: model one point-load intake with conserved momentum

#99
Merged chris wants to merge codex/cargo-fleet-custody into main
45 files +3133 -169
tests/unit/vehicle-sessions.test.tsadded+370-0
Changes to tests/unit/vehicle-sessions.test.ts
@@ -0,0 +1,370 @@
1import { expect, test } from 'bun:test'
2import { createVehicleSimulationSession } from '../../resources/functions/drone/vehicles/runtime'
3import { createMultirotorProfile } from '../../resources/functions/drone/vehicles/multirotor/profile'
4import type { VehiclePayloadCommand } from '../../resources/functions/drone/vehicles/types'
5import type { SensorVector } from '../../resources/functions/drone/sensors/types'
6
7test('two vehicle sessions share policy epochs while their raw sensor and authority scopes remain distinct', () => {
8 const a = createVehicleSimulationSession(createMultirotorProfile(), { seconds: 2, scope: { bootId: 101n, sessionId: 201n } })
9 const b = createVehicleSimulationSession(createMultirotorProfile(), { seconds: 2, scope: { bootId: 102n, sessionId: 202n } })
10 try {
11 expect(() => a.result()).toThrow('still active')
12 for (let nowMs = 0; nowMs <= 1000; nowMs += 4) {
13 const left = a.step(nowMs), right = b.step(nowMs)
14 expect(left.atMs).toBe(right.atMs)
15 expect(left.board.bootId).toBe(101n)
16 expect(right.board.bootId).toBe(102n)
17 if (nowMs === 1000) {
18 expect(left.reference.startsWith('101:')).toBe(true)
19 expect(right.reference.startsWith('102:')).toBe(true)
20 expect(left.authority.sessionId).toBe(201n)
21 expect(right.authority.sessionId).toBe(202n)
22 expect(left.authority.state).toBe('autonomous')
23 expect(right.authority.state).toBe('autonomous')
24 expect(left.board.actuators.some(n => n > 0)).toBe(true)
25 expect(right.board.actuators.some(n => n > 0)).toBe(true)
26 expect(left.policyAtMs).toBe(1000)
27 expect(right.policyAtMs).toBe(1000)
28 }
29 }
30 }
31 finally { a.close(); b.close() }
32 expect(a.result().board.actuators).toEqual([0, 0, 0, 0])
33 expect(b.result().board.actuators).toEqual([0, 0, 0, 0])
34})
35
36test('one vehicle can lose its host and settle independently while the peer continues fresh policy', () => {
37 const profile = createMultirotorProfile(), original = profile.faults
38 profile.faults = (scenario, atMs, phase) => ({ ...original(scenario, atMs, phase), hostLost: atMs >= 740 })
39 const a = createVehicleSimulationSession(profile, { seconds: 2, neutralTailMs: 1000, scope: { bootId: 101n, sessionId: 201n } })
40 const b = createVehicleSimulationSession(createMultirotorProfile(), { seconds: 2, scope: { bootId: 102n, sessionId: 202n } })
41 try {
42 for (let nowMs = 0; nowMs <= 1840; nowMs += 4) {
43 const left = a.step(nowMs), right = b.step(nowMs)
44 if (nowMs >= 844) {
45 expect(left.phase).toBe('independent-tail')
46 expect(left.hostAvailable).toBe(false)
47 expect(left.policyAtMs).toBe(720)
48 expect(left.board.actuators).toEqual([0, 0, 0, 0])
49 }
50 if (nowMs === 1840) {
51 expect(left.terminal).toBe(true)
52 expect(right.terminal).toBe(false)
53 expect(right.hostAvailable).toBe(true)
54 expect(right.policyAtMs).toBe(1840)
55 expect(right.authority.state).toBe('autonomous')
56 expect(right.board.actuators.some(n => n > 0)).toBe(true)
57 }
58 }
59 const run = a.result()
60 expect(run.status).toBe('host-lost')
61 expect(run.board.fault).toBe('output-lease-expired')
62 expect(run.path.at(-1)!.atMs).toBe(720)
63 expect(run.path.at(-1)!.measurement!.reference.startsWith('101:')).toBe(true)
64 expect(() => a.step(1844)).toThrow('closed')
65 }
66 finally { a.close(); b.close() }
67})
68
69test('vehicle sessions reject invalid scope before allocation and invalid epochs without advancing state', () => {
70 const profile = createMultirotorProfile()
71 let opened = false, getterCalled = false
72 profile.createSession = () => { opened = true; throw new Error('Unexpected allocation') }
73 for (const scope of [null, { bootId: 0n, sessionId: 1n }, { bootId: 1n, sessionId: 0x10000000000000000n }, { bootId: 1, sessionId: 2n }, { get bootId() { getterCalled = true; return 1n }, sessionId: 2n }]) {
74 expect(() => createVehicleSimulationSession(profile, { scope: scope as never })).toThrow('scope')
75 }
76 expect(opened).toBe(false)
77 expect(getterCalled).toBe(false)
78 const scope = { bootId: 101n, sessionId: 201n }, session = createVehicleSimulationSession(createMultirotorProfile(), { seconds: 2, scope })
79 scope.bootId = 999n; scope.sessionId = 999n
80 try {
81 expect(() => session.step(4)).toThrow('next 4 ms epoch')
82 expect(session.step(0).board.bootId).toBe(101n)
83 expect(() => session.step(0)).toThrow('next 4 ms epoch')
84 expect(() => session.step(8)).toThrow('next 4 ms epoch')
85 expect(session.step(4).atMs).toBe(4)
86 }
87 finally { session.close() }
88 const result = session.result()
89 expect(result.status).toBe('blocked')
90 expect(result.fault).toBe('simulation-session-closed')
91 result.board.actuators[0] = 99
92 expect(session.result().board.actuators).toEqual([0, 0, 0, 0])
93})
94
95test('a step failure and explicit close both release payload ownership once and revoke the board', () => {
96 for (const fail of [false, true]) {
97 const profile = createMultirotorProfile(), create = profile.createSession
98 let closes = 0
99 profile.createSession = () => {
100 const base = create()
101 return { ...base, renderMeasurement(...args) { if (fail && args[1] === 1000) throw new Error('Captured renderer failure'); return base.renderMeasurement(...args) },
102 createPayload: () => ({ request() {}, poll() { return null }, close() { closes++ } }),
103 }
104 }
105 const session = createVehicleSimulationSession(profile, { seconds: 2 })
106 try {
107 for (let nowMs = 0; nowMs < 1000; nowMs += 4) session.step(nowMs)
108 if (fail) expect(() => session.step(1000)).toThrow('Captured renderer failure')
109 }
110 finally { session.close(); session.close() }
111 expect(closes).toBe(1)
112 expect(session.result().board.actuators).toEqual([0, 0, 0, 0])
113 expect(session.result().board.expiresAtMs).toBeNull()
114 expect(session.result().fault).toBe(fail ? 'simulation-step-failed' : 'simulation-session-closed')
115 expect(() => session.step(1004)).toThrow('closed')
116 }
117})
118
119test('a simultaneous step and teardown failure is retained after the independent board is revoked', () => {
120 const profile = createMultirotorProfile(), create = profile.createSession
121 let closes = 0
122 profile.createSession = () => {
123 const base = create()
124 return { ...base, renderMeasurement(...args) { if (args[1] === 1000) throw new Error('Renderer failed'); return base.renderMeasurement(...args) },
125 createPayload: () => ({ request() {}, poll() { return null }, close() { closes++; throw new Error('Payload teardown failed') } }),
126 }
127 }
128 const session = createVehicleSimulationSession(profile, { seconds: 2 })
129 for (let atMs = 0; atMs < 1000; atMs += 4) session.step(atMs)
130 let failure: unknown
131 try { session.step(1000) }
132 catch (error) { failure = error }
133 expect(failure).toBeInstanceOf(AggregateError)
134 expect((failure as AggregateError).errors.map(error => error.message)).toEqual(['Renderer failed', 'Payload teardown failed'])
135 session.close()
136 expect(closes).toBe(1)
137 expect(session.result().board.actuators).toEqual([0, 0, 0, 0])
138 expect(session.result().board.expiresAtMs).toBeNull()
139})
140
141test('a controller callback cannot reopen the board lease after closing its own session', () => {
142 const profile = createMultirotorProfile(), create = profile.createSession
143 let session: ReturnType<typeof createVehicleSimulationSession>, returnedNonzero = false
144 profile.createSession = () => {
145 const base = create()
146 return { ...base, createController() {
147 const controller = base.createController()
148 return { step(context) {
149 const output = controller.step(context)
150 if (context.nowMs === 1000) { returnedNonzero = output.actuators.some(n => n > 0); session.close() }
151 return output
152 } }
153 } }
154 }
155 session = createVehicleSimulationSession(profile, { seconds: 2 })
156 try {
157 for (let atMs = 0; atMs < 1000; atMs += 4) session.step(atMs)
158 const tick = session.step(1000)
159 expect(returnedNonzero).toBe(true)
160 expect(tick.terminal).toBe(true)
161 expect(tick.hostAvailable).toBe(false)
162 expect(tick.policyAtMs).toBe(980)
163 expect(tick.board.actuators).toEqual([0, 0, 0, 0])
164 expect(tick.board.expiresAtMs).toBeNull()
165 expect(session.result().board.actuators).toEqual([0, 0, 0, 0])
166 expect(session.result().fault).toBe('simulation-session-closed')
167 }
168 finally { session.close() }
169})
170
171test('a controller cannot recursively advance the same in-flight session epoch', () => {
172 const profile = createMultirotorProfile(), create = profile.createSession
173 let session: ReturnType<typeof createVehicleSimulationSession>, attempted = false
174 profile.createSession = () => {
175 const base = create()
176 return { ...base, createController() {
177 const controller = base.createController()
178 return { step(context) {
179 if (context.nowMs === 1000 && !attempted) {
180 attempted = true
181 expect(() => session.step(1000)).toThrow('already stepping')
182 }
183 return controller.step(context)
184 } }
185 } }
186 }
187 session = createVehicleSimulationSession(profile, { seconds: 2 })
188 try {
189 for (let atMs = 0; atMs <= 1000; atMs += 4) session.step(atMs)
190 expect(attempted).toBe(true)
191 expect(session.step(1004).atMs).toBe(1004)
192 }
193 finally { session.close() }
194})
195
196test('closing from a payload observation prevents later polling and controller work in the same epoch', () => {
197 const profile = createMultirotorProfile(), create = profile.createSession
198 let session: ReturnType<typeof createVehicleSimulationSession>, closes = 0, workAfterClose = 0
199 profile.createSession = () => {
200 const base = create()
201 return { ...base, createController() {
202 const controller = base.createController()
203 return { step(context) { if (closes) workAfterClose++; return controller.step(context) } }
204 }, createPayload: () => ({
205 observe(context) { if (context.nowMs === 1000) session.close() },
206 request() { if (closes) workAfterClose++ },
207 poll() { if (closes) workAfterClose++; return null },
208 close() { closes++ },
209 }) }
210 }
211 session = createVehicleSimulationSession(profile, { seconds: 2 })
212 try {
213 for (let atMs = 0; atMs < 1000; atMs += 4) session.step(atMs)
214 const tick = session.step(1000)
215 expect(tick.terminal).toBe(true)
216 expect(tick.policyAtMs).toBe(980)
217 expect(tick.hostAvailable).toBe(false)
218 expect(workAfterClose).toBe(0)
219 expect(closes).toBe(1)
220 expect(tick.board.actuators).toEqual([0, 0, 0, 0])
221 expect(tick.board.expiresAtMs).toBeNull()
222 }
223 finally { session.close() }
224})
225
226test('a closing link callback failure is surfaced without calling the closed payload', () => {
227 const profile = createMultirotorProfile(), create = profile.createSession
228 let session: ReturnType<typeof createVehicleSimulationSession>, closes = 0, observationsAfterClose = 0
229 profile.createSession = () => ({ ...create(),
230 linkObservation(nowMs) {
231 if (nowMs === 1000) { session.close(); throw new Error('Link callback failed after close') }
232 return { capturedAtMs: nowMs, connected: true }
233 },
234 createPayload: () => ({ observe() { if (closes) observationsAfterClose++ }, request() {}, poll() { return null }, close() { closes++ } }),
235 })
236 session = createVehicleSimulationSession(profile, { seconds: 2 })
237 try {
238 for (let atMs = 0; atMs < 1000; atMs += 4) session.step(atMs)
239 expect(() => session.step(1000)).toThrow('Link callback failed after close')
240 expect(observationsAfterClose).toBe(0)
241 expect(closes).toBe(1)
242 expect(session.result().board.actuators).toEqual([0, 0, 0, 0])
243 }
244 finally { session.close() }
245})
246
247test('a returned actuator getter cannot reopen output when capture closes its session', () => {
248 const profile = createMultirotorProfile(), create = profile.createSession
249 let session: ReturnType<typeof createVehicleSimulationSession>, getterCalled = false
250 profile.createSession = () => {
251 const base = create()
252 return { ...base, createController() {
253 const controller = base.createController()
254 return { step(context) {
255 const output = controller.step(context)
256 if (context.nowMs === 1000) {
257 const actuators = [...output.actuators]
258 Object.defineProperty(output, 'actuators', { enumerable: true, get() { getterCalled = true; session.close(); return actuators } })
259 }
260 return output
261 } }
262 } }
263 }
264 session = createVehicleSimulationSession(profile, { seconds: 2 })
265 try {
266 for (let atMs = 0; atMs < 1000; atMs += 4) session.step(atMs)
267 const tick = session.step(1000)
268 expect(getterCalled).toBe(true)
269 expect(tick.terminal).toBe(true)
270 expect(tick.board.actuators).toEqual([0, 0, 0, 0])
271 expect(tick.board.expiresAtMs).toBeNull()
272 expect(tick.policyAtMs).toBe(980)
273 }
274 finally { session.close() }
275})
276
277test('a returned ACK getter cannot confirm payload work after closing its session', () => {
278 const profile = createMultirotorProfile(), create = profile.createSession
279 profile.mission.tasks = [{ id: 'start', kind: 'start', next: 'capture' }, { id: 'capture', kind: 'payload', operation: 'camera-still', containerId: null, timeoutMs: 1500, next: 'depart' }, ...profile.mission.tasks.filter(task => task.kind !== 'start')]
280 let session: ReturnType<typeof createVehicleSimulationSession>, pending: VehiclePayloadCommand | null = null, getterCalled = false
281 profile.createSession = () => ({ ...create(), createPayload: () => ({
282 request(command) { pending = structuredClone(command) },
283 poll(nowMs) {
284 if (!pending || nowMs <= pending.issuedAtMs) return null
285 const command = pending
286 return { eventId: command.eventId, taskId: command.taskId, operation: command.operation, containerId: command.containerId, reference: command.reference,
287 capturedAtMs: nowMs, outcome: 'confirmed', metadata: {}, get positionM(): SensorVector { getterCalled = true; session.close(); return [...command.positionM] } }
288 },
289 close() { pending = null },
290 }) })
291 session = createVehicleSimulationSession(profile, { seconds: 12 })
292 try {
293 for (let atMs = 0; ; atMs += 4) { if (session.step(atMs).terminal) break }
294 expect(getterCalled).toBe(true)
295 expect(session.result().trace.rows.some(row => row.result.reason === 'payload-confirmed')).toBe(false)
296 expect(session.result().fault).toBe('simulation-session-closed')
297 expect(session.result().board.actuators).toEqual([0, 0, 0, 0])
298 }
299 finally { session.close() }
300})
301
302test('a returned fault getter cannot advance the physical plant after closing its session', () => {
303 const profile = createMultirotorProfile(), create = profile.createSession, faults = profile.faults
304 let session: ReturnType<typeof createVehicleSimulationSession>, closed = false, stepsAfterClose = 0, getterCalled = false
305 profile.faults = (scenario, atMs, phase) => atMs !== 1000 ? faults(scenario, atMs, phase) : {
306 get windMps(): SensorVector { getterCalled = true; closed = true; session.close(); return [0, 0, 0] },
307 }
308 profile.createSession = () => {
309 const base = create()
310 return { ...base, createPlant() {
311 const plant = base.createPlant()
312 return { snapshot: plant.snapshot, step(...args) { if (closed) stepsAfterClose++; return plant.step(...args) } }
313 } }
314 }
315 session = createVehicleSimulationSession(profile, { seconds: 2 })
316 try {
317 for (let atMs = 0; atMs <= 1000; atMs += 4) session.step(atMs)
318 expect(getterCalled).toBe(true)
319 expect(stepsAfterClose).toBe(0)
320 expect(session.result().fault).toBe('simulation-session-closed')
321 expect(session.result().board.actuators).toEqual([0, 0, 0, 0])
322 }
323 finally { session.close() }
324})
325
326test('the initial plant snapshot is captured before a live session can close through its getters', () => {
327 const profile = createMultirotorProfile(), create = profile.createSession
328 let session: ReturnType<typeof createVehicleSimulationSession> | undefined, readsAfterExposure = 0, callbacksAfterClose = 0, closed = false
329 profile.createSession = () => {
330 const base = create()
331 return { ...base, createPlant() {
332 const plant = base.createPlant()
333 return { step: plant.step, snapshot() {
334 const state = plant.snapshot()
335 return { ...state, get details() { if (session) { readsAfterExposure++; closed = true; session.close() } return state.details } }
336 } }
337 }, observeIndependent() { if (closed) callbacksAfterClose++ } }
338 }
339 session = createVehicleSimulationSession(profile, { seconds: 2 })
340 try {
341 for (let atMs = 0; atMs <= 1000; atMs += 4) { if (session.step(atMs).terminal) break }
342 expect(readsAfterExposure).toBe(0)
343 expect(callbacksAfterClose).toBe(0)
344 expect(() => session!.result()).toThrow('still active')
345 }
346 finally { session.close() }
347})
348
349test('adapter methods are bound before exposure so method getters cannot close then invoke work', () => {
350 const profile = createMultirotorProfile(), create = profile.createSession
351 let session: ReturnType<typeof createVehicleSimulationSession> | undefined, readsAfterExposure = 0, callbacksAfterClose = 0, closed = false
352 profile.createSession = () => {
353 const base = create()
354 return { ...base, createController() {
355 const controller = base.createController()
356 return { get step() {
357 if (session) { readsAfterExposure++; closed = true; session.close() }
358 return (context: Parameters<typeof controller.step>[0]) => { if (closed) callbacksAfterClose++; return controller.step(context) }
359 } }
360 } }
361 }
362 session = createVehicleSimulationSession(profile, { seconds: 2 })
363 try {
364 for (let atMs = 0; atMs <= 1000; atMs += 4) { if (session.step(atMs).terminal) break }
365 expect(readsAfterExposure).toBe(0)
366 expect(callbacksAfterClose).toBe(0)
367 expect(() => session!.result()).toThrow('still active')
368 }
369 finally { session.close() }
370})