ReviewOS

also looking at this

stacks/drone

feat: coordinate modeled two-carrier cargo handover

#103
Merged chris wants to merge codex/cargo-fleet-coordination into main
25 files +1654 -13
tests/unit/cargo-station.test.tsadded+194-0
Changes to tests/unit/cargo-station.test.ts
@@ -0,0 +1,194 @@
1import { expect, test } from 'bun:test'
2import { createCargoStationHandler } from '../../resources/functions/drone/cargo/station'
3import { createReceivingRigidBody, createRigidBody } from '../../resources/functions/drone/controls/physics'
4
5// Physical function seam: one real separated parcel crosses a finite station path
6// and enters actual receiving dynamics. This is not vehicle authority or a custody ACK.
7test('one separated point load moves continuously to the receiving joint and leaves the station once', () => {
8 const load = { id: 'parcel-a', massKg: .1, forwardM: .08 }
9 const source = createRigidBody({ positionM: [0, 0, 0], carriedPointLoad: load })
10 const receiver = createReceivingRigidBody({ positionM: [1, 0, 0], expectedPointLoad: load })
11 source.step([0, 0, 0, 0], .004); receiver.step([0, 0, 0, 0], .004)
12 const release = source.separateCarriedLoad()
13 if (release.outcome !== 'separated') throw new Error('Expected actual source separation')
14 const station = createCargoStationHandler({ atMs: 4, parcel: { id: load.id, ...release.parcel }, pickup: { centerM: [.08, 0, 0], radiusM: .1 }, destinationM: receiver.intakePoint().positionM, maxSpeedMps: .5, maxAccelerationMps2: 1 })
15 expect(station.snapshot().ownedMassKg).toBe(.1)
16 expect(source.loadSnapshot().properties.totalMassKg + receiver.loadSnapshot().properties.totalMassKg + station.snapshot().ownedMassKg).toBe(3.1)
17 expect(station.start()).toEqual({ outcome: 'started', atMs: 4, durationMs: 3752 })
18 let previous = station.snapshot().parcel!.positionM
19 for (let nowMs = 8; nowMs <= 3756; nowMs += 4) {
20 receiver.step([0, 0, 0, 0], .004)
21 const state = station.step(nowMs), parcel = state.parcel!
22 expect(Math.hypot(...parcel.positionM.map((n, i) => n - previous[i]!))).toBeLessThanOrEqual(.002 + 1e-12)
23 if (nowMs === 1880) { expect(parcel.positionM[0]).toBeCloseTo(.58, 14); expect(parcel.velocityMps[0]).toBeCloseTo(.4997334754797441, 13) }
24 previous = parcel.positionM
25 }
26 expect(station.snapshot().phase).toBe('ready')
27 const exit = station.takeReadyParcel()
28 if (exit.outcome !== 'departed') throw new Error('Expected actual station exit')
29 expect(receiver.attachParcel(exit.parcel).outcome).toBe('attached')
30 expect(station.snapshot().parcel).toBeNull()
31 expect(station.snapshot().ownedMassKg).toBe(0)
32 expect(source.loadSnapshot().properties.totalMassKg + receiver.loadSnapshot().properties.totalMassKg).toBe(3.1)
33 expect(station.takeReadyParcel()).toEqual({ outcome: 'refused', reason: 'not-ready' })
34 expect(Math.abs(station.snapshot().energy.residualJ)).toBeLessThan(1e-12)
35})
36
37test('the actual released point falls before surface capture and retains its impact energy and epoch', () => {
38 const load = { id: 'parcel-a', massKg: .1, forwardM: .08 }, gravity = 9.80665
39 const source = createRigidBody({ positionM: [0, 0, -1], carriedPointLoad: load })
40 source.step([0, 0, 0, 0], .004)
41 const release = source.separateCarriedLoad()
42 if (release.outcome !== 'separated') throw new Error('Expected airborne source separation')
43 const initial = release.parcel, v0 = initial.velocityMps[2], height = -initial.positionM[2]
44 const hitAtMs = 4 + 1000 * (Math.sqrt(v0 ** 2 + 2 * gravity * height) - v0) / gravity
45 const station = createCargoStationHandler({ atMs: 4, parcel: { id: load.id, ...initial }, pickup: { centerM: [.08, 0, 0], radiusM: .1 }, destinationM: [1.08, 0, 0], maxSpeedMps: .5, maxAccelerationMps2: 1 })
46 expect(station.snapshot().phase).toBe('falling')
47 expect(station.start()).toEqual({ outcome: 'refused', reason: 'not-held' })
48 let nowMs = 4
49 while (station.snapshot().phase === 'falling') {
50 nowMs += 4
51 const state = station.step(nowMs), seconds = (nowMs - 4) / 1000
52 expect(Math.abs(state.energy.residualJ)).toBeLessThan(1e-12)
53 if (state.phase === 'falling') expect(state.parcel!.positionM[2]).toBeCloseTo(initial.positionM[2] + v0 * seconds + .5 * gravity * seconds ** 2, 12)
54 expect(nowMs).toBeLessThan(1000)
55 }
56 const landed = station.snapshot()
57 expect(landed.phase).toBe('held')
58 expect(landed.parcel!.positionM).toEqual([.08, 0, 0])
59 expect(landed.parcel!.velocityMps).toEqual([0, 0, 0])
60 expect(landed.impact!.atMs).toBeCloseTo(hitAtMs, 9)
61 expect(landed.impact!.impulseNs[2]).toBeCloseTo(-.1 * Math.sqrt(v0 ** 2 + 2 * gravity * height), 12)
62 expect(landed.energy.planeDissipationJ).toBeCloseTo(.05 * v0 ** 2 + .1 * gravity * height, 12)
63 expect(landed.energy.stationNetWorkJ).toBe(0)
64 expect(station.start().outcome).toBe('started')
65})
66
67test('cancellation brakes the real moving parcel finitely and retains it instead of transferring it', () => {
68 const station = createCargoStationHandler({ atMs: 4, parcel: { id: 'parcel-a', massKg: .1, positionM: [.08, 0, 0], velocityMps: [0, 0, 0] }, pickup: { centerM: [.08, 0, 0], radiusM: .1 }, destinationM: [1.08, 0, 0], maxSpeedMps: .5, maxAccelerationMps2: 1 })
69 station.start()
70 for (let atMs = 8; atMs <= 1880; atMs += 4) station.step(atMs)
71 const before = station.snapshot(), v0 = before.parcel!.velocityMps[0]
72 expect(station.cancel()).toEqual({ outcome: 'cancelling', atMs: 1880 })
73 expect(station.snapshot().phase).toBe('braking')
74 expect(station.snapshot().parcel).toEqual(before.parcel)
75 expect(station.takeReadyParcel()).toEqual({ outcome: 'refused', reason: 'not-ready' })
76 let atMs = 1880, previous = before.parcel!
77 while (station.snapshot().phase === 'braking') {
78 atMs += 4
79 const row = station.step(atMs), p = row.parcel!
80 expect(p.velocityMps[0]).toBeGreaterThanOrEqual(0)
81 expect(p.velocityMps[0]).toBeLessThan(previous.velocityMps[0])
82 expect(Math.abs(p.velocityMps[0] - previous.velocityMps[0])).toBeLessThanOrEqual(.004 + 1e-12)
83 expect(Math.hypot(...p.positionM.map((n, i) => n - previous.positionM[i]!))).toBeLessThanOrEqual(.002 + 1e-12)
84 expect(Math.abs(row.energy.residualJ)).toBeLessThan(1e-12)
85 expect(atMs).toBeLessThan(2500)
86 previous = p
87 }
88 const stopped = station.snapshot()
89 expect(stopped.phase).toBe('cancelled')
90 expect(stopped.parcel!.velocityMps).toEqual([0, 0, 0])
91 expect(stopped.parcel!.positionM[0]).toBeCloseTo(.58 + v0 ** 2 / 2, 12)
92 expect(stopped.stoppedAtMs).toBeCloseTo(1880 + v0 * 1000, 9)
93 expect(stopped.ownedMassKg).toBe(.1)
94 expect(station.start()).toEqual({ outcome: 'refused', reason: 'not-held' })
95 expect(station.cancel()).toEqual({ outcome: 'refused', reason: 'already-cancelled' })
96 expect(station.step(atMs + 4).parcel).toEqual(stopped.parcel)
97})
98
99test('a drifting parcel misses the declared pickup instead of being pulled onto the rail', () => {
100 const station = createCargoStationHandler({ atMs: 0, parcel: { id: 'parcel-a', massKg: .1, positionM: [0, 0, -1], velocityMps: [1, 0, 0] }, pickup: { centerM: [0, 0, 0], radiusM: .1 }, destinationM: [1, 0, 0], maxSpeedMps: .5, maxAccelerationMps2: 1 })
101 let atMs = 0
102 while (station.snapshot().phase === 'falling') station.step(atMs += 4)
103 const missed = station.snapshot()
104 expect(missed.phase).toBe('missed')
105 // Independent one-metre drop: flight time sqrt(2/g), with constant 1 m/s north velocity.
106 expect(missed.parcel!.positionM[0]).toBeCloseTo(Math.sqrt(2 / 9.80665), 12)
107 expect(missed.energy.planeDissipationJ).toBeCloseTo(1.030665, 12)
108 expect(missed.impact!.impulseNs[0]).toBe(-.1)
109 expect(missed.ownedMassKg).toBe(.1)
110 expect(Math.abs(missed.energy.residualJ)).toBeLessThan(1e-12)
111 expect(station.start()).toEqual({ outcome: 'refused', reason: 'not-held' })
112 expect(station.takeReadyParcel()).toEqual({ outcome: 'refused', reason: 'not-ready' })
113 expect(station.step(atMs + 4).parcel).toEqual(missed.parcel)
114})
115
116test('cancelling a rising parcel retains gravity and impact before it can settle', () => {
117 const station = createCargoStationHandler({ atMs: 0, parcel: { id: 'parcel-a', massKg: .1, positionM: [0, 0, 0], velocityMps: [0, 0, -1] }, pickup: { centerM: [0, 0, 0], radiusM: .1 }, destinationM: [1, 0, 0], maxSpeedMps: .5, maxAccelerationMps2: 1 })
118 expect(station.cancel()).toEqual({ outcome: 'cancelling', atMs: 0 })
119 expect(station.snapshot().phase).toBe('falling')
120 expect(station.snapshot().forceN).toEqual([0, 0, 0])
121 expect(station.step(4).parcel!.positionM[2]).toBeCloseTo(-.0039215468, 12)
122 let atMs = 4
123 while (station.snapshot().phase === 'falling') station.step(atMs += 4)
124 const stopped = station.snapshot()
125 expect(stopped.phase).toBe('cancelled')
126 expect(stopped.impact!.atMs).toBeCloseTo(2000 / 9.80665, 9)
127 expect(stopped.stoppedAtMs).toBe(stopped.impact!.atMs)
128 expect(stopped.energy.planeDissipationJ).toBeCloseTo(.05, 12)
129 expect(stopped.energy.stationNetWorkJ).toBe(0)
130 expect(Math.abs(stopped.energy.residualJ)).toBeLessThan(1e-12)
131 expect(station.start().outcome).toBe('refused')
132 expect(station.takeReadyParcel().outcome).toBe('refused')
133})
134
135test('lifting retains mechanical work and speed/acceleration limits on the full spatial path', () => {
136 const station = createCargoStationHandler({ atMs: 0, parcel: { id: 'parcel-a', massKg: .2, positionM: [0, 0, 0], velocityMps: [0, 0, 0] }, pickup: { centerM: [0, 0, 0], radiusM: .1 }, destinationM: [1, 2, -1], maxSpeedMps: .5, maxAccelerationMps2: 1 })
137 station.start()
138 let atMs = 0, previous = station.snapshot()
139 while (station.snapshot().phase === 'moving') {
140 const row = station.step(atMs += 4)
141 expect(Math.hypot(...row.parcel!.velocityMps)).toBeLessThanOrEqual(.5 + 1e-12)
142 expect(Math.hypot(...row.parcel!.velocityMps.map((n, i) => (n - previous.parcel!.velocityMps[i]!) / .004))).toBeLessThanOrEqual(1 + 1e-12)
143 expect(Math.abs(row.energy.residualJ)).toBeLessThan(1e-12)
144 previous = row
145 }
146 expect(previous.parcel!.positionM).toEqual([1, 2, -1])
147 expect(Math.hypot(...previous.parcel!.velocityMps)).toBe(0)
148 expect(previous.energy.stationNetWorkJ).toBeCloseTo(1.96133, 12)
149 expect(previous.energy.positiveWorkJ).toBeGreaterThanOrEqual(previous.energy.stationNetWorkJ)
150 expect(previous.energy.positiveWorkJ + previous.energy.negativeWorkJ).toBeCloseTo(previous.energy.stationNetWorkJ, 12)
151 expect(station.takeReadyParcel().outcome).toBe('departed')
152 expect(station.snapshot().energy.departedJ).toBeCloseTo(1.96133, 12)
153 expect(Math.abs(station.snapshot().energy.residualJ)).toBeLessThan(1e-12)
154})
155
156test('station admission captures data without invoking caller accessors and rejects invalid declarations privately', () => {
157 const input = { atMs: 0, parcel: { id: 'parcel-a', massKg: .1, positionM: [0, 0, 0], velocityMps: [0, 0, 0] }, pickup: { centerM: [0, 0, 0], radiusM: .1 }, destinationM: [1, 0, 0], maxSpeedMps: .5, maxAccelerationMps2: 1 }
158 const station = createCargoStationHandler(input), original = station.snapshot()
159 input.parcel.positionM[0] = 20; input.parcel.massKg = .2; input.pickup.centerM[0] = 10; input.destinationM[0] = 40
160 const detached = station.snapshot()
161 detached.parcel!.positionM[0] = 88; detached.impact!.impulseNs[0] = 19; detached.energy.initialJ = 500
162 expect(station.snapshot()).toEqual(original)
163 expect(station.start()).toEqual({ outcome: 'started', atMs: 0, durationMs: 3752 })
164 expect(station.start()).toEqual({ outcome: 'refused', reason: 'not-held' })
165 const fresh = { atMs: 0, parcel: { id: 'parcel-a', massKg: .1, positionM: [0, 0, 0], velocityMps: [0, 0, 0] }, pickup: { centerM: [0, 0, 0], radiusM: .1 }, destinationM: [1, 0, 0], maxSpeedMps: .5, maxAccelerationMps2: 1 }
166 const getter = structuredClone(fresh)
167 let invoked = 0
168 Object.defineProperty(getter.parcel, 'positionM', { enumerable: true, get() { invoked++; throw new Error('private-source') } })
169 const revoked = Proxy.revocable({}, {}); revoked.revoke()
170 const bad = [null, {}, { ...fresh, extra: true }, { ...fresh, atMs: 3 }, { ...fresh, atMs: -4 }, { ...fresh, atMs: Number.MAX_SAFE_INTEGER }, { ...fresh, maxSpeedMps: 0 }, { ...fresh, maxAccelerationMps2: Infinity }, { ...fresh, parcel: { ...fresh.parcel, massKg: .251 } }, { ...fresh, parcel: { ...fresh.parcel, positionM: [0, 0, .01] } }, { ...fresh, parcel: { ...fresh.parcel, positionM: [0, 0, -3.01] } }, { ...fresh, parcel: { ...fresh.parcel, velocityMps: [0, 0, NaN] } }, { ...fresh, destinationM: [50, 0, 0] }, getter, revoked.proxy]
171 for (const v of bad) expect(() => createCargoStationHandler(v)).toThrow('cargo-station-constructor')
172 expect(invoked).toBe(0)
173})
174
175test('invalid and exhausted clocks cannot change the parcel, and delayed starts preserve the lifetime bound', () => {
176 const config = { atMs: 0, parcel: { id: 'parcel-a', massKg: .1, positionM: [0, 0, 0], velocityMps: [0, 0, 0] }, pickup: { centerM: [0, 0, 0], radiusM: .1 }, destinationM: [1, 0, 0], maxSpeedMps: .5, maxAccelerationMps2: 1 }
177 const station = createCargoStationHandler(config), initial = station.snapshot()
178 for (const invalid of [0, -4, 1, 8, NaN, Infinity]) expect(() => station.step(invalid)).toThrow('cargo-station-clock')
179 expect(() => station.step(4, 'extra')).toThrow('cargo-station-clock')
180 expect(() => station.start('extra')).toThrow('cargo-station-arguments')
181 expect(() => station.cancel('extra')).toThrow('cargo-station-arguments')
182 expect(() => station.takeReadyParcel('extra')).toThrow('cargo-station-arguments')
183 expect(station.snapshot()).toEqual(initial)
184 for (let atMs = 4; atMs <= 179996; atMs += 4) station.step(atMs)
185 const held = station.snapshot()
186 expect(station.start()).toEqual({ outcome: 'refused', reason: 'deadline' })
187 expect(station.snapshot()).toEqual(held)
188 station.step(180000)
189 const end = station.snapshot()
190 expect(() => station.step(180004)).toThrow('cargo-station-clock')
191 expect(station.snapshot()).toEqual(end)
192 expect(station.cancel()).toEqual({ outcome: 'cancelled', atMs: 180000 })
193 expect(station.takeReadyParcel().outcome).toBe('refused')
194})