ReviewOS

also looking at this

stacks/drone

feat: add shared-clock scoped vehicle simulation sessions

#98
Merged chris wants to merge codex/cargo-fleet-runtime into main
42 files +2764 -127
resources/functions/drone/vehicles/links.tsadded+62-0
Changes to resources/functions/drone/vehicles/links.ts
@@ -0,0 +1,62 @@
1import { authorityPolicy } from '../authority/supervisor'
2
3export interface VehicleLinkScope { vehicleId: string, bootId: number, sessionId: number }
4export type VehicleLinkSource = 'primary' | 'backup'
5interface Packet extends VehicleLinkScope { sourceId: VehicleLinkSource, sequence: number, capturedAtMs: number, receivedAtMs: number, clockUncertaintyMs: number, connected: boolean }
6const fields = ['vehicleId', 'bootId', 'sessionId', 'sourceId', 'sequence', 'capturedAtMs', 'receivedAtMs', 'clockUncertaintyMs', 'connected']
7function captureData(input: unknown, keys: string[]): Record<string, unknown> | null {
8 if (!input || typeof input !== 'object' || Object.getPrototypeOf(input) !== Object.prototype || Reflect.ownKeys(input).length !== keys.length) return null
9 const captured: Record<string, unknown> = {}
10 for (const key of keys) {
11 const d = Object.getOwnPropertyDescriptor(input, key)
12 if (!d || !d.enumerable || !Object.hasOwn(d, 'value')) return null
13 captured[key] = d.value
14 }
15 return captured
16}
17
18/** Two captured sources for one authority owner. Scope labels are not authentication. */
19export function createRedundantVehicleLinks(input: VehicleLinkScope) {
20 const data = captureData(input, ['vehicleId', 'bootId', 'sessionId'])
21 if (!data || typeof data.vehicleId !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(data.vehicleId) || typeof data.bootId !== 'number' || !Number.isSafeInteger(data.bootId) || data.bootId < 1 || typeof data.sessionId !== 'number' || !Number.isSafeInteger(data.sessionId) || data.sessionId < 1) throw new TypeError('Invalid vehicle link scope')
22 const scope = { vehicleId: data.vehicleId, bootId: data.bootId, sessionId: data.sessionId }, packets = new Map<VehicleLinkSource, Packet>()
23 let lastNow = -1, seenHealthy = false, latchedLoss = false
24 function clock(nowMs: number) {
25 if (!Number.isSafeInteger(nowMs) || nowMs < 0 || nowMs < lastNow) throw new RangeError('Invalid vehicle link clock')
26 lastNow = nowMs
27 }
28 function fresh(packet: Packet, nowMs: number) {
29 return packet.connected && nowMs - packet.capturedAtMs + packet.clockUncertaintyMs <= authorityPolicy.linkAgeMs
30 }
31 function checkLoss(nowMs: number) {
32 if (seenHealthy && ![...packets.values()].some(packet => fresh(packet, nowMs))) latchedLoss = true
33 }
34 return {
35 ingest(input: unknown, nowMs: number): boolean {
36 clock(nowMs)
37 checkLoss(nowMs)
38 const captured = captureData(input, fields)
39 if (latchedLoss || !captured) return false
40 if (captured.vehicleId !== scope.vehicleId || captured.bootId !== scope.bootId || captured.sessionId !== scope.sessionId || !['primary', 'backup'].includes(captured.sourceId as string)
41 || typeof captured.connected !== 'boolean' || !['sequence', 'capturedAtMs', 'receivedAtMs', 'clockUncertaintyMs'].every(key => Number.isSafeInteger(captured[key]) && Number(captured[key]) >= 0)) return false
42 const packet = captured as unknown as Packet, previous = packets.get(packet.sourceId)
43 if (packet.sequence < 1 || packet.clockUncertaintyMs > 10 || packet.capturedAtMs < packet.clockUncertaintyMs || packet.capturedAtMs + packet.clockUncertaintyMs > packet.receivedAtMs || packet.receivedAtMs > nowMs
44 || nowMs - packet.capturedAtMs + packet.clockUncertaintyMs > authorityPolicy.linkAgeMs || previous && (packet.sequence <= previous.sequence || packet.capturedAtMs <= previous.capturedAtMs || packet.receivedAtMs < previous.receivedAtMs)) return false
45 packets.set(packet.sourceId, { ...packet })
46 if (packet.connected) seenHealthy = true
47 return true
48 },
49 snapshot(nowMs: number) {
50 clock(nowMs)
51 checkLoss(nowMs)
52 const candidates = (['primary', 'backup'] as const).filter(id => { const packet = packets.get(id); return packet && fresh(packet, nowMs) })
53 if (candidates.length) seenHealthy = true
54 else if (seenHealthy) latchedLoss = true
55 const selectedSource = latchedLoss ? null : candidates[0] ?? null, selected = selectedSource ? packets.get(selectedSource)! : null
56 return { evidence: 'scoped-captured-link-selection' as const, scope: { ...scope }, observedAtMs: nowMs, selectedSource, latchedLoss,
57 authority: { capturedAtMs: selected ? selected.capturedAtMs - selected.clockUncertaintyMs : 0, connected: selected !== null },
58 sources: (['primary', 'backup'] as const).map(sourceId => { const packet = packets.get(sourceId); return { sourceId, sequence: packet?.sequence ?? null, capturedAtMs: packet?.capturedAtMs ?? null, receivedAtMs: packet?.receivedAtMs ?? null, clockUncertaintyMs: packet?.clockUncertaintyMs ?? null, connected: packet ? fresh(packet, nowMs) : false } }),
59 identityAuthenticated: false as const, physicalFlightEnabled: false as const }
60 },
61 }
62}