also looking at this
feat: add scoped cargo receiving mission tasks
#102
21 files
+1186
-15
| @@ -0,0 +1,194 @@ | ||
| 1 | import { expect, test } from 'bun:test' | |
| 2 | import { createCargoStationHandler } from '../../resources/functions/drone/cargo/station' | |
| 3 | import { 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. | |
| 7 | test('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 | ||
| 37 | test('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 | ||
| 67 | test('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 | ||
| 99 | test('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 | ||
| 116 | test('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 | ||
| 135 | test('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 | ||
| 156 | test('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 | ||
| 175 | test('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 | }) | |