ReviewOS

also looking at this

stacks/drone

feat: model phase-bound cargo fleet failures

#104
Merged chris wants to merge codex/cargo-fleet-phase-faults into main
25 files +1844 -13
tests/unit/cargo-fleet.test.tsadded+289-0
Changes to tests/unit/cargo-fleet.test.ts
@@ -0,0 +1,289 @@
1import { expect, test } from 'bun:test'
2import { simulateCargoFleet } from '../../resources/functions/drone/cargo/fleet'
3
4// Public fleet seam: two actual raw-sensor/estimator/authority sessions share a
5// world clock. No mocked body, custody state, mechanism ACK or preloaded receiver.
6test('one source parcel crosses the finite station into a live receiver and completes its second delivery', () => {
7 const run = simulateCargoFleet()
8 expect(run.evidence).toBe('owned-cargo-fleet-simulation')
9 expect(run.physicalFlightEnabled).toBe(false)
10 expect(run.identityAuthenticated).toBe(false)
11 expect(run.status).toBe('completed')
12 expect(run.source.runtime.status).toBe('completed')
13 expect(run.receiver.runtime.status).toBe('completed')
14 expect(run.source.initialLoad.properties.totalMassKg).toBe(1.6)
15 expect(run.receiver.initialLoad.properties.totalMassKg).toBe(1.5)
16 expect(run.receiver.initialLoad.properties.phase).toBe('awaiting')
17 expect(run.source.runtime.board.bootId).toBe(101n)
18 expect(run.receiver.runtime.board.bootId).toBe(102n)
19 expect(run.source.runtime.authority.sessionId).toBe(201n)
20 expect(run.receiver.runtime.authority.sessionId).toBe(202n)
21 expect(run.transfer.sourceRelease!.event.outcome).toBe('separated')
22 expect(run.transfer.stationDeparture!.outcome).toBe('departed')
23 const intake = run.transfer.intake!
24 expect(intake.attachment.outcome).toBe('attached')
25 if (intake.attachment.outcome !== 'attached') throw new Error('Expected actual modeled intake')
26 expect(intake.attachment.before.properties.totalMassKg).toBe(1.5)
27 expect(intake.attachment.after.properties.totalMassKg).toBe(1.6)
28 expect(intake.receiver.atMs).toBe(intake.source.atMs)
29 expect(intake.receiver.policyAtMs).toBeGreaterThanOrEqual(intake.atMs - 20)
30 expect(intake.receiver.authority.state).toBe('autonomous')
31 expect(intake.receiver.authority.sessionId).toBe(202n)
32 expect(intake.source.hostAvailable).toBe(true)
33 expect(intake.source.reference.startsWith('101:')).toBe(true)
34 expect(intake.receiver.reference.startsWith('102:')).toBe(true)
35 expect(run.source.delivery.outcome).toBe('received')
36 expect(run.receiver.intake.custody.outcome).toBe('received')
37 expect(run.receiver.delivery.outcome).toBe('received')
38 expect(run.receiver.intake.custody.acknowledgedAtMs!).toBeGreaterThan(intake.atMs)
39 expect(run.receiver.intake.custody.receiptCapturedAtMs!).toBeGreaterThanOrEqual(intake.atMs)
40 expect(run.receiver.finalLoad.properties.phase).toBe('separated')
41 expect(run.receiver.finalLoad.properties.totalMassKg).toBe(1.5)
42 expect(run.ownership.transitions.map(row => [row.from, row.to])).toEqual([
43 ['source-body', 'station-actor'], ['station-actor', 'receiver-body'], ['receiver-body', 'final-parcel-actor'],
44 ])
45 expect(run.ownership.initialMassKg).toBe(3.1)
46 expect(run.ownership.finalMassKg).toBe(3.1)
47 expect(run.ownership.maximumMassErrorKg).toBeLessThan(1e-12)
48 expect(run.ownership.samples).toBeGreaterThan(1000)
49 expect(run.station!.ownedMassKg).toBe(0)
50 expect(run.recipient!.ownedMassKg).toBe(.1)
51 expect(run.recipient!.phase).toBe('held')
52 expect(run.transfer.stationDeparture!.atMs).toBeGreaterThan(run.transfer.sourceRelease!.atMs + 1000)
53})
54
55test('receiver host loss after its grant but before actual intake retains the one parcel at the station', () => {
56 const run = simulateCargoFleet({ scenario: 'receiver-host-loss-before-intake' })
57 expect(run.status).toBe('unqualified')
58 expect(run.source.runtime.status).toBe('completed')
59 expect(run.source.delivery.outcome).toBe('received')
60 expect(run.receiver.runtime.status).toBe('host-lost')
61 expect(run.receiver.runtime.board.fault).toBe('output-lease-expired')
62 expect(run.receiver.runtime.board.actuators).toEqual([0, 0, 0, 0])
63 // The frozen supervisor snapshot alone still says autonomous. The physical
64 // mechanism must also check actual same-epoch host availability and lease age.
65 expect(run.receiver.runtime.authority.state).toBe('autonomous')
66 expect(run.transfer.intake).toBeNull()
67 expect(run.transfer.stationDeparture).toBeNull()
68 expect(run.receiver.finalLoad.properties.phase).toBe('awaiting')
69 expect(run.receiver.finalLoad.properties.totalMassKg).toBe(1.5)
70 expect(run.receiver.intake.custody.outcome).toBe('uncertain')
71 expect(run.receiver.delivery.outcome).toBe('not-released')
72 expect(run.faultInjection!.triggeredAtMs).toBe(run.receiver.intake.custody.grantedAtMs! + 4)
73 expect(run.receiver.runtime.path.at(-1)!.atMs).toBe(run.receiver.intake.custody.grantedAtMs!)
74 expect(run.station!.phase).toBe('cancelled')
75 expect(run.station!.ownedMassKg).toBe(.1)
76 expect(run.recipient).toBeNull()
77 expect(run.ownership.transitions.map(row => [row.from, row.to])).toEqual([['source-body', 'station-actor']])
78 expect(run.ownership.finalMassKg).toBe(3.1)
79 expect(run.ownership.maximumMassErrorKg).toBeLessThan(1e-12)
80})
81
82test('lost intake receipt keeps actual mass on the receiver and follows its counted alternate without claiming custody', () => {
83 const run = simulateCargoFleet({ scenario: 'intake-receipt-loss' })
84 expect(run.status).toBe('unqualified')
85 expect(run.transfer.intake!.attachment.outcome).toBe('attached')
86 expect(run.transfer.finalRelease).toBeNull()
87 expect(run.receiver.intake.custody.outcome).toBe('uncertain')
88 expect(run.receiver.intake.custody.receiptCapturedAtMs).toBeNull()
89 expect(run.receiver.runtime.status).toBe('completed')
90 expect(run.receiver.runtime.mission.reason).toBe('payload-diversion-landed')
91 expect(run.receiver.runtime.mission.payloadFailure).toMatchObject({ taskId: 'intake', reason: 'uncertain', landingTaskId: 'alternate-land' })
92 expect(run.receiver.finalLoad.properties.phase).toBe('attached')
93 expect(run.receiver.finalLoad.properties.totalMassKg).toBe(1.6)
94 expect(run.receiver.delivery.outcome).toBe('not-released')
95 // The declared alternate accepts a 0.18 m radius, not centimetre accuracy.
96 expect(Math.hypot(run.receiver.runtime.finalTruthPositionM[0] - 5, run.receiver.runtime.finalTruthPositionM[1] - 3)).toBeLessThanOrEqual(.18)
97 expect(run.ownership.transitions.map(row => row.to)).toEqual(['station-actor', 'receiver-body'])
98 expect(run.ownership.finalMassKg).toBe(3.1)
99 expect(run.ownership.maximumMassErrorKg).toBeLessThan(1e-12)
100 expect(run.station!.ownedMassKg).toBe(0)
101 expect(run.recipient).toBeNull()
102 expect(run.faultInjection!.triggeredAtMs!).toBeGreaterThanOrEqual(run.transfer.intake!.atMs)
103 expect(run.receiver.intake.custody.grantedAtMs).toBe(run.transfer.intake!.grant.issuedAtMs)
104})
105
106test('fleet scenario admission rejects unknown fields and accessors before opening a world', () => {
107 let invoked = false
108 for (const input of [null, [], 'nominal', { scenario: 'unknown-private-marker' }, { scenario: undefined }, { physical: true }, { get scenario() { invoked = true; return 'nominal' } }]) expect(() => simulateCargoFleet(input)).toThrow('cargo-fleet-arguments')
109 expect(invoked).toBe(false)
110 expect(() => simulateCargoFleet({}, 'extra')).toThrow('cargo-fleet-arguments')
111})
112
113test('the receiving vehicle can lose its primary radio during station handling and finish on its own captured backup link', () => {
114 const run = simulateCargoFleet({ scenario: 'receiver-primary-link-loss' })
115 expect(run.status).toBe('completed')
116 expect(run.receiver.intake.custody.outcome).toBe('received')
117 expect(run.receiver.delivery.outcome).toBe('received')
118 expect(run.source.links.scope).toEqual({ vehicleId: 'carrier-a', bootId: 101, sessionId: 201 })
119 expect(run.receiver.links.scope).toEqual({ vehicleId: 'carrier-b', bootId: 102, sessionId: 202 })
120 expect(run.source.links.selectedSource).toBe('primary')
121 expect(run.receiver.links.selectedSource).toBe('backup')
122 expect(run.receiver.links.latchedLoss).toBe(false)
123 expect(run.receiver.linkEvents.some(row => row.selectedSource === 'backup')).toBe(true)
124 expect(run.faultInjection!.triggeredAtMs!).toBeGreaterThanOrEqual(run.faultInjection!.anchoredAtMs!)
125 expect(run.transfer.intake!.atMs).toBeGreaterThan(run.faultInjection!.triggeredAtMs!)
126 expect(run.ownership.finalMassKg).toBe(3.1)
127})
128
129test('loss of both receiver radios expires its own authority and brakes station transport while the source continues', () => {
130 const run = simulateCargoFleet({ scenario: 'receiver-both-links-loss' })
131 expect(run.status).toBe('unqualified')
132 expect(run.source.runtime.status).toBe('completed')
133 expect(run.source.links.latchedLoss).toBe(false)
134 expect(run.receiver.links.latchedLoss).toBe(true)
135 expect(run.receiver.links.selectedSource).toBeNull()
136 expect(run.receiver.runtime.status).toBe('blocked')
137 expect(run.receiver.runtime.authority.state).toBe('failsafe')
138 expect(run.receiver.runtime.authority.reason).toBe('link-loss')
139 expect(run.receiver.runtime.board.actuators).toEqual([0, 0, 0, 0])
140 expect(run.receiver.finalLoad.properties.phase).toBe('awaiting')
141 expect(run.transfer.intake).toBeNull()
142 expect(run.transfer.stationDeparture).toBeNull()
143 expect(run.station!.phase).toBe('cancelled')
144 expect(run.station!.startedAtMs).not.toBeNull()
145 expect(run.station!.cancelRequestedAtMs!).toBeGreaterThanOrEqual(run.station!.startedAtMs!)
146 expect(run.station!.stoppedAtMs!).toBeGreaterThanOrEqual(run.station!.cancelRequestedAtMs!)
147 expect(run.station!.ownedMassKg).toBe(.1)
148 expect(Math.hypot(...run.station!.parcel!.velocityMps)).toBe(0)
149 expect(run.ownership.owner).toBe('station-actor')
150 expect(run.ownership.finalMassKg).toBe(3.1)
151})
152
153test('a real receiver joint shift refuses stale rendezvous and the departed point falls without duplication', () => {
154 const run = simulateCargoFleet({ scenario: 'receiver-joint-shift-before-intake' })
155 expect(run.status).toBe('unqualified')
156 expect(run.transfer.intake!.attachment).toEqual({ outcome: 'refused', reason: 'mount-not-coincident' })
157 expect(run.receiver.finalLoad.properties.phase).toBe('awaiting')
158 expect(run.receiver.finalLoad.properties.totalMassKg).toBe(1.5)
159 expect(run.receiver.intake.custody.outcome).toBe('rejected')
160 expect(run.receiver.intake.custody.mechanismAtMs).toBe(run.transfer.intake!.atMs)
161 expect(run.receiver.runtime.mission.payloadFailure!.reason).toBe('rejected')
162 expect(run.receiver.runtime.mission.reason).toBe('payload-diversion-landed')
163 expect(run.transfer.finalRelease).toBeNull()
164 expect(run.recipient).toBeNull()
165 expect(run.station!.ownedMassKg).toBe(0)
166 expect(run.loose!.ownedMassKg).toBe(.1)
167 expect(run.loose!.phase).toBe('held')
168 expect(run.loose!.parcel!.positionM[2]).toBe(0)
169 expect(run.loose!.impact!.atMs).toBeGreaterThan(run.transfer.intake!.atMs)
170 expect(run.ownership.owner).toBe('loose-parcel')
171 expect(run.ownership.finalMassKg).toBe(3.1)
172 expect(run.ownership.maximumMassErrorKg).toBeLessThan(1e-12)
173})
174
175test('receiver GNSS loss at actual station rail start expires navigation and brakes transport while its peer continues', () => {
176 const run = simulateCargoFleet({ scenario: 'receiver-navigation-loss-during-rail' })
177 expect(run.status).toBe('unqualified')
178 expect(run.source.runtime.status).toBe('completed')
179 expect(run.source.delivery.outcome).toBe('received')
180 expect(run.receiver.runtime.status).toBe('blocked')
181 expect(run.receiver.runtime.authority.state).toBe('failsafe')
182 expect(run.receiver.runtime.authority.reason).toBe('stale-estimator')
183 expect(run.receiver.runtime.fault).toBe('estimator-loss')
184 expect(run.receiver.runtime.board.actuators).toEqual([0, 0, 0, 0])
185 expect(run.receiver.finalLoad.properties.phase).toBe('awaiting')
186 expect(run.receiver.finalLoad.properties.totalMassKg).toBe(1.5)
187 expect(run.transfer.stationDeparture).toBeNull()
188 expect(run.transfer.intake).toBeNull()
189 expect(run.station!.phase).toBe('cancelled')
190 expect(run.station!.ownedMassKg).toBe(.1)
191 expect(run.station!.startedAtMs).toBe(run.faultInjection!.anchoredAtMs)
192 expect(run.faultInjection!.triggeredAtMs).toBe(run.faultInjection!.anchoredAtMs! + 4)
193 expect(run.station!.cancelRequestedAtMs!).toBeGreaterThan(run.faultInjection!.triggeredAtMs!)
194 expect(run.station!.stoppedAtMs!).toBeGreaterThanOrEqual(run.station!.cancelRequestedAtMs!)
195 expect(Math.hypot(...run.station!.parcel!.velocityMps)).toBe(0)
196 expect(run.ownership.owner).toBe('station-actor')
197 expect(run.ownership.finalMassKg).toBe(3.1)
198})
199
200test('source kill after captured station custody inhibits only that carrier while the receiver finishes the one parcel delivery', () => {
201 const run = simulateCargoFleet({ scenario: 'source-kill-after-station-receipt' })
202 expect(run.status).toBe('unqualified')
203 expect(run.source.runtime.status).toBe('blocked')
204 expect(run.source.runtime.authority.state).toBe('killed')
205 expect(run.source.runtime.board.actuators).toEqual([0, 0, 0, 0])
206 expect(run.source.delivery.outcome).toBe('received')
207 expect(run.receiver.runtime.status).toBe('completed')
208 expect(run.receiver.intake.custody.outcome).toBe('received')
209 expect(run.receiver.delivery.outcome).toBe('received')
210 expect(run.transfer.intake!.atMs).toBeGreaterThan(run.faultInjection!.triggeredAtMs!)
211 expect(run.faultInjection!.anchoredAtMs).toBe(run.source.delivery.acknowledgedAtMs)
212 expect(run.faultInjection!.triggeredAtMs).toBe(run.faultInjection!.anchoredAtMs! + 4)
213 expect(run.ownership.owner).toBe('final-parcel-actor')
214 expect(run.station!.ownedMassKg).toBe(0)
215 expect(run.recipient!.ownedMassKg).toBe(.1)
216 expect(run.ownership.finalMassKg).toBe(3.1)
217})
218
219test('receiver kill immediately after actual intake retains its real added mass without inventing captured custody', () => {
220 const run = simulateCargoFleet({ scenario: 'receiver-kill-after-intake' })
221 expect(run.status).toBe('unqualified')
222 expect(run.source.runtime.status).toBe('completed')
223 expect(run.source.delivery.outcome).toBe('received')
224 expect(run.receiver.runtime.status).toBe('blocked')
225 expect(run.receiver.runtime.authority.state).toBe('killed')
226 expect(run.receiver.runtime.board.actuators).toEqual([0, 0, 0, 0])
227 expect(run.transfer.intake!.attachment.outcome).toBe('attached')
228 expect(run.receiver.finalLoad.properties.totalMassKg).toBe(1.6)
229 expect(run.receiver.finalLoad.properties.phase).toBe('attached')
230 expect(run.receiver.intake.custody.outcome).toBe('uncertain')
231 expect(run.receiver.intake.custody.receiptCapturedAtMs).toBeNull()
232 expect(run.receiver.intake.custody.acknowledgedAtMs).toBeNull()
233 expect(run.faultInjection!.anchoredAtMs).toBe(run.transfer.intake!.atMs)
234 expect(run.faultInjection!.triggeredAtMs).toBe(run.transfer.intake!.atMs + 4)
235 expect(run.transfer.finalRelease).toBeNull()
236 expect(run.recipient).toBeNull()
237 expect(run.station!.ownedMassKg).toBe(0)
238 expect(run.ownership.owner).toBe('receiver-body')
239 expect(run.ownership.finalMassKg).toBe(3.1)
240})
241
242test('receiver pad motion trips receiving interlocks and brakes the station before any intake', () => {
243 const run = simulateCargoFleet({ scenario: 'receiver-pad-motion-during-rail' })
244 expect(run.status).toBe('unqualified')
245 expect(run.source.runtime.status).toBe('completed')
246 expect(run.source.delivery.outcome).toBe('received')
247 expect(run.receiver.runtime.status).toBe('blocked')
248 expect(run.receiver.runtime.authority.state).toBe('disarmed')
249 expect(run.receiver.runtime.fault).toBe('material-receive-interlocks')
250 expect(run.receiver.runtime.finalTruthPositionM[0]).toBeGreaterThan(3)
251 expect(Math.hypot(run.receiver.runtime.finalTruthPositionM[0], run.receiver.runtime.finalTruthPositionM[1])).toBeLessThan(12)
252 expect(run.receiver.runtime.board.actuators).toEqual([0, 0, 0, 0])
253 expect(run.receiver.finalLoad.properties.phase).toBe('awaiting')
254 expect(run.transfer.intake).toBeNull()
255 expect(run.transfer.stationDeparture).toBeNull()
256 expect(run.station!.phase).toBe('cancelled')
257 expect(run.station!.ownedMassKg).toBe(.1)
258 expect(run.station!.startedAtMs).toBe(run.faultInjection!.anchoredAtMs)
259 expect(run.station!.cancelRequestedAtMs!).toBeGreaterThan(run.faultInjection!.triggeredAtMs!)
260 expect(run.ownership.owner).toBe('station-actor')
261 expect(run.ownership.finalMassKg).toBe(3.1)
262})
263
264test('receiver containment during loaded departure revokes authority on actual fence motion while preserving received custody', () => {
265 const run = simulateCargoFleet({ scenario: 'receiver-containment-breach-after-intake-receipt' })
266 expect(run.status).toBe('unqualified')
267 expect(run.source.runtime.status).toBe('completed')
268 expect(run.source.delivery.outcome).toBe('received')
269 expect(run.receiver.runtime.status).toBe('blocked')
270 expect(run.receiver.runtime.authority.state).toBe('failsafe')
271 expect(run.receiver.runtime.authority.reason).toBe('fence-breach')
272 expect(run.receiver.runtime.fault).toBe('mission-fence-breach')
273 expect(run.receiver.runtime.navigationEvidence.localPositionHealthy).toBe(true)
274 expect(run.receiver.runtime.navigationEvidence.positionPrediction?.mode).toBe('fixture-imu')
275 expect(run.faultInjection).toMatchObject({ forceN: [8, 0, 0], forceRampMs: 2000 })
276 expect(Math.hypot(run.receiver.runtime.finalTruthPositionM[0], run.receiver.runtime.finalTruthPositionM[1])).toBeGreaterThan(12)
277 expect(run.receiver.runtime.board.actuators).toEqual([0, 0, 0, 0])
278 expect(run.receiver.finalLoad.properties.phase).toBe('attached')
279 expect(run.receiver.finalLoad.properties.totalMassKg).toBe(1.6)
280 expect(run.receiver.intake.custody.outcome).toBe('received')
281 expect(run.receiver.intake.custody.acknowledgedAtMs).toBe(run.faultInjection!.anchoredAtMs)
282 expect(run.faultInjection!.triggeredAtMs).toBe(run.faultInjection!.anchoredAtMs! + 4)
283 expect(run.transfer.finalRelease).toBeNull()
284 expect(run.receiver.delivery.outcome).toBe('not-released')
285 expect(run.station!.phase).toBe('departed')
286 expect(run.station!.ownedMassKg).toBe(0)
287 expect(run.ownership.owner).toBe('receiver-body')
288 expect(run.ownership.finalMassKg).toBe(3.1)
289})