ReviewOS

also looking at this

stacks/drone

feat: add scoped cargo receiving mission tasks

#102
Merged chris wants to merge codex/cargo-fleet-authority into main
21 files +1186 -15
tests/unit/cargo-receive-mission.test.tsadded+149-0
Changes to tests/unit/cargo-receive-mission.test.ts
@@ -0,0 +1,149 @@
1import { expect, test } from 'bun:test'
2import type { VehicleMissionObservation, VehiclePayloadCommand } from '../../resources/functions/drone/vehicles/types'
3import { createReceivingRigidBody } from '../../resources/functions/drone/controls/physics'
4import { createVehicleSimulationSession } from '../../resources/functions/drone/vehicles/runtime'
5import { createMultirotorPlant, createMultirotorProfile, multirotorMission } from '../../resources/functions/drone/vehicles/multirotor/profile'
6import { createVehicleMissionEngine, parseVehicleMissionTrace, replayVehicleMission, validateVehicleMission } from '../../resources/functions/drone/missions/vehicle'
7
8function receivePlan() {
9 const spatial = { acceptanceM: .2, maxArrivalSpeedMps: .18, settleMs: 200, timeoutMs: 10000 }
10 return { ...multirotorMission(), id: 'cargo-receiver', tasks: [
11 { id: 'start', kind: 'start', next: 'intake' },
12 { id: 'intake', kind: 'payload', operation: 'material-receive', containerId: 'parcel-a', positionM: [3, 2, -.1], timeoutMs: 60000, next: 'depart', onFailure: 'divert' },
13 { id: 'depart', kind: 'takeoff', positionM: [3, 2, -1], ...spatial, next: 'land' },
14 { id: 'land', kind: 'land', positionM: [3, 2, 0], ...spatial },
15 { id: 'divert', kind: 'waypoint', positionM: [4, 2, -1], ...spatial, timeoutMs: 8000, next: 'alternate' },
16 { id: 'alternate', kind: 'land', positionM: [4, 2, 0], ...spatial, timeoutMs: 8000 },
17 ] }
18}
19function observation(nowMs: number): VehicleMissionObservation {
20 return { kind: 'simulation', nowMs, reference: '102:0,0,0,0,0', origin: { latitudeDeg: 0, longitudeDeg: 0, ellipsoidHeightM: 100 }, healthy: true, positionM: [3, 2, -.1], velocityMps: [0, 0, 0], authority: 'autonomous', batteryPercent: 98, onGround: true, payloadAck: null }
21}
22
23// Native mission function seam: proves receipt command, anchor, scope and counted
24// plan behavior. It does not produce mechanical intake or current payload authority.
25test('a receiving mission holds its declared pad and advances only after its own correlated receipt ACK', () => {
26 const plan = receivePlan(), validated = validateVehicleMission(plan)
27 expect(validated.worstCaseMs).toBe(80020)
28 const engine = createVehicleMissionEngine(plan)
29 expect(engine.step(observation(600), 'start')).toMatchObject({ taskId: 'intake', state: 'running', targetM: [3, 2, -.1] })
30 const pending = engine.step(observation(620)).payload!
31 expect(pending).toMatchObject({ taskId: 'intake', operation: 'material-receive', containerId: 'parcel-a', reference: '102:0,0,0,0,0', issuedAtMs: 600, expiresAtMs: 60600 })
32 const result = engine.step({ ...observation(640), payloadAck: { eventId: pending.eventId, taskId: pending.taskId, operation: pending.operation, containerId: pending.containerId, reference: pending.reference, positionM: pending.positionM, capturedAtMs: 640, outcome: 'confirmed' } })
33 expect(result.taskId).toBe('depart')
34 expect(result.reason).toBe('payload-confirmed')
35 expect(result.payload).toBeNull()
36 expect(replayVehicleMission(engine.trace()).snapshot()).toEqual(result)
37 expect(parseVehicleMissionTrace(JSON.stringify(engine.trace()))).toEqual(engine.trace())
38})
39
40
41// Actual receiving body plus raw-sensor/estimator/authority runtime. The only
42// external fixture is a payload wire that withholds its ACK, not an intake mock.
43test('an unacknowledged receiving mission keeps its actual parked body neutral under its own live authority', () => {
44 const body = createReceivingRigidBody({ positionM: [3, 2, -.1], groundDownM: -.1, expectedPointLoad: { id: 'parcel-a', massKg: .1, forwardM: .08 } })
45 const profile = createMultirotorProfile(), create = profile.createSession
46 profile.mission = validateVehicleMission(receivePlan()).plan
47 const commands: VehiclePayloadCommand[] = []
48 profile.createSession = () => ({ ...create(), createPlant: () => createMultirotorPlant(body), createPayload: () => ({ request(command) { commands.push(structuredClone(command)) }, poll() { return null }, close() {} }) })
49 const session = createVehicleSimulationSession(profile, { seconds: 3, scope: { bootId: 102n, sessionId: 202n } })
50 try {
51 for (let nowMs = 0; nowMs <= 2000; nowMs += 4) {
52 const row = session.step(nowMs)
53 if (nowMs >= 600) {
54 expect(row.authority.state).toBe('autonomous')
55 expect(row.authority.sessionId).toBe(202n)
56 expect(row.reference.startsWith('102:')).toBe(true)
57 expect(row.board.actuators).toEqual([0, 0, 0, 0])
58 expect(body.snapshot().positionM).toEqual([3, 2, -.1])
59 expect(body.snapshot().motorsN).toEqual([0, 0, 0, 0])
60 expect(body.loadSnapshot().properties.totalMassKg).toBe(1.5)
61 }
62 }
63 expect(commands).toHaveLength(1)
64 expect(commands[0]!.operation).toBe('material-receive')
65 expect(commands[0]!.issuedAtMs).toBe(600)
66 expect(body.loadSnapshot().properties.phase).toBe('awaiting')
67 }
68 finally { session.close() }
69})
70
71test('a foreign, stale or uncertain receipt takes only the declared counted failure route', () => {
72 for (const changed of [
73 { reference: '101:0,0,0,0,0' }, { eventId: 'source-vehicle-event' }, { containerId: 'parcel-b' },
74 { capturedAtMs: 599 }, { capturedAtMs: 641 }, { outcome: 'uncertain' as const }, { outcome: 'rejected' as const },
75 ]) {
76 const engine = createVehicleMissionEngine(receivePlan())
77 const request = engine.step(observation(600), 'start').payload!
78 const ack = { eventId: request.eventId, taskId: request.taskId, operation: request.operation, containerId: request.containerId, reference: request.reference, positionM: request.positionM, capturedAtMs: 620, outcome: 'confirmed' as 'confirmed' | 'uncertain' | 'rejected', ...changed }
79 const row = engine.step({ ...observation(640), payloadAck: ack })
80 expect(row.taskId).toBe('divert')
81 expect(row.payloadFailure).toMatchObject({ taskId: 'intake', operation: 'material-receive', approachTaskId: 'divert', landingTaskId: 'alternate' })
82 expect(row.payload).toBeNull()
83 expect(row.reason).toBe('payload-failure-diversion')
84 }
85})
86
87test('receiving cannot start or accept an ACK away from its pad, moving or without contact', () => {
88 for (const change of [{ onGround: false }, { positionM: [3, 2, -.31] as [number, number, number] }, { velocityMps: [.101, 0, 0] as [number, number, number] }]) {
89 for (const atEntry of [true, false]) {
90 const engine = createVehicleMissionEngine(receivePlan())
91 let result
92 if (atEntry) result = engine.step({ ...observation(600), ...change }, 'start')
93 else {
94 const pending = engine.step(observation(600), 'start').payload!
95 result = engine.step({ ...observation(620), ...change, payloadAck: { eventId: pending.eventId, taskId: pending.taskId, operation: pending.operation, containerId: pending.containerId, reference: pending.reference, positionM: pending.positionM, capturedAtMs: 620, outcome: 'confirmed' } })
96 }
97 expect(result.state).toBe('blocked')
98 expect(result.payload).toBeNull()
99 expect(result.taskId).not.toBe('depart')
100 expect(result.targetM).toBeNull()
101 }
102 }
103})
104
105test('receipt expiry diverts once and cannot be cleared by a late ACK', () => {
106 const engine = createVehicleMissionEngine(receivePlan())
107 const pending = engine.step(observation(600), 'start').payload!
108 for (let atMs = 620; atMs <= 60600; atMs += 20) engine.step(observation(atMs))
109 const timedOut = engine.snapshot()
110 expect(timedOut.taskId).toBe('divert')
111 expect(timedOut.payloadFailure).toMatchObject({ reason: 'timeout', triggeredAtMs: 60600 })
112 const late = engine.step({ ...observation(60620), payloadAck: { eventId: pending.eventId, taskId: pending.taskId, operation: pending.operation, containerId: pending.containerId, reference: pending.reference, positionM: pending.positionM, capturedAtMs: 60600, outcome: 'confirmed' } })
113 expect(late.state).toBe('blocked')
114 expect(late.taskId).toBe('divert')
115 expect(late.reason).toBe('unsolicited-payload-ack')
116})
117
118test('receipt validation preserves finite graph reserve and rejects unsupported profiles, missing anchors and retry paths', () => {
119 for (const change of [
120 (p: ReturnType<typeof receivePlan>) => { p.vehicle = 'ground' },
121 (p: ReturnType<typeof receivePlan>) => { Reflect.set(p.tasks[1]!, 'containerId', null) },
122 (p: ReturnType<typeof receivePlan>) => { delete p.tasks[1]!.positionM },
123 (p: ReturnType<typeof receivePlan>) => { p.tasks[1]!.positionM = [3, 2, -1.001] },
124 (p: ReturnType<typeof receivePlan>) => { p.tasks[1]!.timeoutMs = 60001 },
125 (p: ReturnType<typeof receivePlan>) => { p.tasks[1]!.timeoutMs = 100.5 },
126 (p: ReturnType<typeof receivePlan>) => { p.tasks[5]!.next = 'intake' },
127 (p: ReturnType<typeof receivePlan>) => { p.tasks[1]!.onFailure = 'depart' },
128 (p: ReturnType<typeof receivePlan>) => { p.tasks[3]!.timeoutMs = 60000; p.tasks[5]!.timeoutMs = 60000; p.power.availableWh = 20 },
129 ]) {
130 const input = receivePlan(); change(input)
131 expect(() => validateVehicleMission(input)).toThrow()
132 }
133 const alternateBudget = receivePlan()
134 alternateBudget.tasks[3]!.timeoutMs = 1000; alternateBudget.tasks[4]!.timeoutMs = 30000; alternateBudget.tasks[5]!.timeoutMs = 30000
135 expect(validateVehicleMission(alternateBudget).worstCaseMs).toBe(120020)
136})
137
138test('missing or nonfinite ACK coordinates cannot confirm receipt or create an unreplayable accepted trace', () => {
139 for (const position of [Array<number>(3), [3, , -.1], [NaN, 2, -.1], [3, 2, Infinity]]) {
140 const engine = createVehicleMissionEngine(receivePlan()), pending = engine.step(observation(600), 'start').payload!
141 const ack = { eventId: pending.eventId, taskId: pending.taskId, operation: pending.operation, containerId: pending.containerId, reference: pending.reference, positionM: position as [number, number, number], capturedAtMs: 620, outcome: 'confirmed' as const }
142 expect(() => engine.step({ ...observation(620), payloadAck: ack })).toThrow('Invalid vehicle mission observation')
143 expect(engine.snapshot().state).toBe('blocked')
144 expect(engine.snapshot().taskId).toBe('intake')
145 expect(engine.snapshot().payload).toBeNull()
146 expect(engine.snapshot().reason).not.toBe('payload-confirmed')
147 expect(() => parseVehicleMissionTrace(JSON.stringify(engine.trace()))).not.toThrow()
148 }
149})