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-intake-coordinator.test.tsadded+150-0
Changes to tests/unit/cargo-intake-coordinator.test.ts
@@ -0,0 +1,150 @@
1import { expect, test } from 'bun:test'
2import type { SensorVector } from '../../resources/functions/drone/sensors/types'
3import type { VehicleControllerContext, VehiclePayloadCommand } from '../../resources/functions/drone/vehicles/types'
4import { vehicleReference } from '../../resources/functions/drone/vehicles/measurements'
5import { observation } from '../fixtures/authority/context'
6import { createCargoIntakeCoordinator } from '../../resources/functions/drone/cargo/intake'
7
8const declaration = () => ({ origin: { latitudeDeg: 0, longitudeDeg: 0, ellipsoidHeightM: 100 }, padM: [3, 2, -.1], receiverId: 'carrier-b', containerId: 'parcel-a', massKg: .1, bootId: 102n, sessionId: 202n })
9
10test('modeled intake captures its declaration and rejects mechanism accessors before invoking them', () => {
11 let invoked = 0
12 const unsafe = { evidence: 'modeled-cargo-intake-mechanism' as const, get request() { invoked++; return () => {} }, cancel() {} }
13 expect(() => createCargoIntakeCoordinator(declaration(), unsafe)).toThrow('cargo-intake-mechanism')
14 expect(invoked).toBe(0)
15 const input = declaration(), adapter = { evidence: 'modeled-cargo-intake-mechanism' as const, request() {}, cancel() {} }
16 const coordinator = createCargoIntakeCoordinator(input, adapter), first = coordinator.snapshot()
17 input.massKg = .2; input.padM[0] = 8
18 const detached = coordinator.snapshot(); detached.declaration.padM[0] = 77
19 expect(coordinator.snapshot()).toEqual(first)
20 expect(first.physicalFlightEnabled).toBe(false)
21 expect(first.identityAuthenticated).toBe(false)
22 expect(first.custody.outcome).toBe('not-requested')
23 coordinator.port.close(); coordinator.port.close()
24})
25
26// Public observed-input policy seam. Declared transport captures exercise receipt
27// admission; actual acquisition, bodies and mechanical authority use fleet tests.
28function context(nowMs: number, sequence: number, payload: VehiclePayloadCommand | null = null): VehicleControllerContext {
29 const estimate = observation(nowMs).estimate
30 estimate.bootId = 102n
31 estimate.localPosition!.origin = declaration().origin
32 estimate.localPosition!.positionM = [3, 2, -.1]
33 estimate.localPosition!.covarianceBlocks = [0, 1, 2].map(() => ({ positionM2: .0001, positionVelocityM2S: 0, velocityM2S2: .0001 }))
34 const reference = vehicleReference(estimate), capturedAtMs = nowMs - 40
35 return { nowMs, enabled: true, estimate,
36 measurement: { version: 1, evidence: 'modeled-vehicle-sensors', vehicle: 'quadcopter', sequence, reference, capturedAtMs, receivedAtMs: nowMs,
37 values: { onSurface: true, stopped: true, receiverId: 'carrier-b', siteClear: true, loadAttached: false, stationReady: true, stationContainerId: 'parcel-a', stationSourceEventId: 'source-delivery:release', intakeEventId: '' } },
38 measurementPose: { capturedAtMs, reference, positionM: [3, 2, -.1], quaternionWxyz: [1, 0, 0, 0], positionCapturedAtMs: capturedAtMs, positionPredictedToMs: capturedAtMs, attitudeCapturedAtMs: capturedAtMs, attitudePredictedToMs: capturedAtMs, gyroCapturedAtMs: capturedAtMs, attitudePrediction: 'qualified-gyro-hold' },
39 controlRate: { evidence: 'modeled-qualified-imu', capturedAtMs: nowMs, reference, angularRateRadS: [0, 0, 0] },
40 mission: { version: 2, vehicle: 'quadcopter', evidence: 'owned-vehicle-mission-simulation', physicalFlightEnabled: false, state: 'running', taskId: 'intake', taskKind: 'payload', targetM: [3, 2, -.1], payload, reason: 'task-entered', elapsedMs: 0 } }
41}
42function command(): VehiclePayloadCommand {
43 return { eventId: 'receiving:intake', taskId: 'intake', operation: 'material-receive', containerId: 'parcel-a', issuedAtMs: 1000, expiresAtMs: 5000, positionM: [3, 2, -.1], reference: vehicleReference(context(1000, 1).estimate) }
44}
45function ready(coordinator: ReturnType<typeof createCargoIntakeCoordinator>) {
46 const request = command()
47 coordinator.port.observe!(context(1000, 1, request)); coordinator.port.request(request)
48 for (let i = 1; i <= 25; i++) coordinator.port.observe!(context(1000 + i * 20, i + 1, request))
49 expect(coordinator.snapshot().readiness.captures).toBe(26)
50 expect(coordinator.port.poll(1500)).toBeNull()
51 expect(coordinator.snapshot().grant).not.toBeNull()
52 return request
53}
54function attached(request: VehiclePayloadCommand, positionM: SensorVector = [3, 2, -.1]) {
55 const c = context(1560, 27, request)
56 c.measurementPose!.positionM = positionM
57 Object.assign(c.measurement!.values, { intakeEventId: request.eventId, intakeSourceEventId: 'source-delivery:release', intakeAtMs: 1504, intakeOutcome: 'attached', loadAttached: true, intakeMassKg: .1 })
58 return c
59}
60
61test('captured attached receipt cannot commit custody with an out-of-bound or distant ACK position', () => {
62 for (const position of [[2000000, 2, -.1], [4.01, 2, -.1]] as SensorVector[]) {
63 const coordinator = createCargoIntakeCoordinator(declaration(), { evidence: 'modeled-cargo-intake-mechanism', request() {}, cancel() {} })
64 const request = ready(coordinator)
65 coordinator.port.observe!(attached(request, position))
66 expect(coordinator.port.poll(1560)).toBeNull()
67 expect(coordinator.snapshot().custody).toMatchObject({ outcome: 'uncertain', receiptCapturedAtMs: null, acknowledgedAtMs: null })
68 coordinator.port.close()
69 }
70})
71
72test('ordinary capture pose commits a correlated receipt exactly once after the intake event', () => {
73 const coordinator = createCargoIntakeCoordinator(declaration(), { evidence: 'modeled-cargo-intake-mechanism', request() {}, cancel() {} })
74 const request = ready(coordinator)
75 coordinator.port.observe!(attached(request))
76 expect(coordinator.port.poll(1560)).toMatchObject({ eventId: request.eventId, outcome: 'confirmed', capturedAtMs: 1520, positionM: [3, 2, -.1] })
77 expect(coordinator.snapshot().custody).toMatchObject({ outcome: 'received', mechanismAtMs: 1504, receiptCapturedAtMs: 1520, acknowledgedAtMs: 1560 })
78 expect(coordinator.port.poll(1560)).toBeNull()
79 coordinator.port.close()
80})
81
82test('nonfinite or negative navigation source epochs cannot accumulate readiness or issue an intake grant', () => {
83 for (const capturedAtMs of [NaN, Infinity, -Infinity, -1]) {
84 const sent: unknown[] = []
85 const coordinator = createCargoIntakeCoordinator(declaration(), { evidence: 'modeled-cargo-intake-mechanism', request: value => { sent.push(value) }, cancel() {} })
86 const request = command()
87 for (let i = 0; i <= 25; i++) {
88 const c = context(1000 + i * 20, i + 1, request)
89 c.estimate.localPosition!.capturedAtMs = capturedAtMs
90 coordinator.port.observe!(c)
91 if (i === 0) coordinator.port.request(request)
92 }
93 expect(coordinator.port.poll(1500)).toBeNull()
94 expect(coordinator.snapshot().readiness.captures).toBe(0)
95 expect(coordinator.snapshot().grant).toBeNull()
96 expect(sent).toEqual([])
97 coordinator.port.close()
98 }
99})
100
101test('valid fractional navigation capture epochs still permit the observed readiness window', () => {
102 const sent: unknown[] = []
103 const coordinator = createCargoIntakeCoordinator(declaration(), { evidence: 'modeled-cargo-intake-mechanism', request: value => { sent.push(value) }, cancel() {} })
104 const request = command()
105 for (let i = 0; i <= 25; i++) {
106 const c = context(1000 + i * 20, i + 1, request)
107 c.estimate.localPosition!.capturedAtMs = c.nowMs - .25
108 coordinator.port.observe!(c)
109 if (i === 0) coordinator.port.request(request)
110 }
111 expect(coordinator.port.poll(1500)).toBeNull()
112 expect(coordinator.snapshot().readiness.captures).toBe(26)
113 expect(sent).toHaveLength(1)
114 coordinator.port.close()
115})
116
117for (const reentry of ['close', 'poll'] as const) test(`terminal uncertainty revokes pending ownership before cancellation can reenter ${reentry}`, () => {
118 const cancelled: string[] = [], reentrantAcks: unknown[] = []
119 const coordinator = createCargoIntakeCoordinator(declaration(), { evidence: 'modeled-cargo-intake-mechanism', request() {}, cancel(eventId) {
120 cancelled.push(eventId)
121 if (reentry === 'close') coordinator.port.close()
122 else reentrantAcks.push(coordinator.port.poll(1560))
123 } })
124 const request = ready(coordinator), foreign = context(1560, 27, request)
125 foreign.measurement!.values.intakeEventId = 'another-vehicle:intake'
126 coordinator.port.observe!(foreign)
127 const ack = coordinator.port.poll(1560)
128 if (reentry === 'close') expect(ack).toBeNull()
129 else {
130 expect(ack).toMatchObject({ eventId: request.eventId, outcome: 'uncertain' })
131 expect(reentrantAcks).toEqual([null])
132 }
133 expect(cancelled).toEqual([request.eventId])
134 expect(coordinator.snapshot().custody).toMatchObject({ outcome: 'uncertain', reason: 'intake-receipt-unqualified', receiptCapturedAtMs: null, acknowledgedAtMs: reentry === 'close' ? null : 1560 })
135 expect(coordinator.snapshot().grant).toBeNull()
136 expect(coordinator.port.poll(1560)).toBeNull()
137 coordinator.port.close(); coordinator.port.close()
138 expect(cancelled).toEqual([request.eventId])
139 expect(() => coordinator.port.request(request)).toThrow('cargo-intake-command-replayed')
140})
141
142test('the intake port rejects a negative first clock without accepting or consuming any observation', () => {
143 const coordinator = createCargoIntakeCoordinator(declaration(), { evidence: 'modeled-cargo-intake-mechanism', request() {}, cancel() {} })
144 expect(() => coordinator.port.observe!(context(-1, 1))).toThrow('cargo-intake-clock')
145 expect(() => coordinator.port.poll(-1)).toThrow('cargo-intake-clock')
146 expect(coordinator.snapshot().readiness.captures).toBe(0)
147 const request = ready(coordinator)
148 expect(coordinator.snapshot().grant!.command).toEqual(request)
149 coordinator.port.close()
150})