also looking at this
feat: expose owned VTOL transition simulation through native CLI
#82
20 files
+743
-36
| @@ -1,9 +1,36 @@ | ||
| 1 | 1 | import type { EstimatorSnapshot } from '../estimation/estimator' |
| 2 | import type { VehicleKind, VehicleMeasurement } from './types' | |
| 2 | import type { VehicleBatteryModel, VehicleBatteryObservation, VehicleKind, VehicleMeasurement, VehicleMissionPlan } from './types' | |
| 3 | 3 | export function vehicleReference(estimate: EstimatorSnapshot) { return `${estimate.bootId}:${Object.values(estimate.resets).join(',')}` } |
| 4 | ||
| 5 | /** Capture a declared source envelope before allocating a simulation session. */ | |
| 6 | export function captureVehicleBatteryModel(input: unknown, power: VehicleMissionPlan['power']): VehicleBatteryModel | null { | |
| 7 | if (input === undefined) return null | |
| 8 | function invalid(): never { throw new TypeError('Invalid modeled vehicle battery envelope') } | |
| 9 | if (!input || typeof input !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(input)) || Reflect.ownKeys(input).length !== 3) invalid() | |
| 10 | const values: Record<string, unknown> = {} | |
| 11 | for (const key of ['evidence', 'capacityWh', 'maximumSourceW']) { | |
| 12 | const descriptor = Object.getOwnPropertyDescriptor(input, key) | |
| 13 | if (!descriptor || !('value' in descriptor)) invalid() | |
| 14 | values[key] = descriptor.value | |
| 15 | } | |
| 16 | const { evidence, capacityWh, maximumSourceW } = values | |
| 17 | if (evidence !== 'modeled-vehicle-battery-v1' || typeof capacityWh !== 'number' || !Number.isFinite(capacityWh) || capacityWh < 0.01 || capacityWh > 10000 || typeof maximumSourceW !== 'number' || !Number.isFinite(maximumSourceW) || maximumSourceW < 1 || maximumSourceW > 100000) invalid() | |
| 18 | if (capacityWh !== power.availableWh) throw new RangeError('Mission capacity differs from modeled battery capacity') | |
| 19 | if (power.maxW < maximumSourceW) throw new RangeError('Vehicle planning power is below modeled source envelope') | |
| 20 | return Object.freeze({ evidence, capacityWh, maximumSourceW }) | |
| 21 | } | |
| 22 | ||
| 23 | /** Qualified capture plus a worst-case age charge, never a current plant-state shortcut. */ | |
| 24 | export function observeVehicleBattery(measurement: VehicleMeasurement, model: VehicleBatteryModel, nowMs: number): VehicleBatteryObservation { | |
| 25 | const energyUsedWh = measurement.values.batteryEnergyUsedWh as number | |
| 26 | const remainingWhLowerBound = Math.max(0, model.capacityWh - energyUsedWh - model.maximumSourceW * (nowMs - measurement.capturedAtMs) / 3600000) | |
| 27 | return { evidence: 'modeled-vehicle-battery-v1', observedAtMs: nowMs, capturedAtMs: measurement.capturedAtMs, sequence: measurement.sequence, reference: measurement.reference, energyUsedWh, remainingWhLowerBound, remainingPercentLowerBound: remainingWhLowerBound / model.capacityWh * 100, | |
| 28 | sourcePowerW: measurement.values.batterySourcePowerW as number, loadPowerW: measurement.values.batteryLoadPowerW as number, currentA: measurement.values.batteryCurrentA as number, terminalV: measurement.values.batteryTerminalV as number, cutoff: measurement.values.batteryCutoff as boolean } | |
| 29 | } | |
| 4 | 30 | /** Shared envelope qualification. Domain adapters still validate physical quantities and units. */ |
| 5 | export function createVehicleMeasurementQualifier(vehicle: VehicleKind) { | |
| 31 | export function createVehicleMeasurementQualifier(vehicle: VehicleKind, batteryModel?: VehicleBatteryModel) { | |
| 6 | 32 | let reference: string | null = null, sequence = 0, captured = -Infinity, signature = '', now = -Infinity |
| 33 | let energyUsedWh = 0, batteryCutoff = false | |
| 7 | 34 | return { |
| 8 | 35 | qualify(input: VehicleMeasurement | null, atMs: number, expectedReference: string): VehicleMeasurement | null { |
| 9 | 36 | if (!Number.isSafeInteger(atMs) || atMs < 0 || atMs < now) throw new RangeError('Vehicle measurement clock must be monotonic') |
| @@ -14,6 +41,14 @@ export function createVehicleMeasurementQualifier(vehicle: VehicleKind) { | ||
| 14 | 41 | for (const [key, value] of Object.entries(m.values)) if (key.length > 80 || !(typeof value === 'boolean' || typeof value === 'string' && value.length <= 160 || typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= 1e8 || Array.isArray(value) && value.length <= 32 && value.every(n => typeof n === 'number' && Number.isFinite(n) && Math.abs(n) <= 1e8))) throw new TypeError('Invalid vehicle measurement values') |
| 15 | 42 | const encoded = JSON.stringify(m) |
| 16 | 43 | if (reference !== null && (reference !== m.reference || m.sequence < sequence || m.sequence === sequence && encoded !== signature || m.sequence > sequence && m.capturedAtMs <= captured)) throw new TypeError('Replayed vehicle measurement or changed reference') |
| 44 | if (batteryModel) { | |
| 45 | const v = m.values | |
| 46 | if (v.batteryCapacityWh !== batteryModel.capacityWh || !['batteryEnergyUsedWh', 'batterySourcePowerW', 'batteryLoadPowerW', 'batteryCurrentA', 'batteryTerminalV'].every(key => typeof v[key] === 'number' && Number.isFinite(v[key]) && (v[key] as number) >= 0) | |
| 47 | || (v.batteryEnergyUsedWh as number) < energyUsedWh || (v.batteryEnergyUsedWh as number) > batteryModel.capacityWh || (v.batterySourcePowerW as number) > batteryModel.maximumSourceW || (v.batteryLoadPowerW as number) > (v.batterySourcePowerW as number) + 0.002 | |
| 48 | || (v.batteryCurrentA as number) > 1000 || (v.batteryTerminalV as number) > 1000 || Math.abs((v.batteryLoadPowerW as number) - (v.batteryCurrentA as number) * (v.batteryTerminalV as number)) > 0.1 | |
| 49 | || v.batteryLoadPowerW === 0 && v.batteryCurrentA !== 0 || typeof v.batteryCutoff !== 'boolean' || batteryCutoff && !v.batteryCutoff) throw new TypeError('Unqualified modeled vehicle battery') | |
| 50 | energyUsedWh = v.batteryEnergyUsedWh as number; batteryCutoff = v.batteryCutoff | |
| 51 | } | |
| 17 | 52 | reference = m.reference; sequence = m.sequence; captured = m.capturedAtMs; signature = encoded |
| 18 | 53 | return m |
| 19 | 54 | }, |