ReviewOS

also looking at this

stacks/drone

feat: model VTOL electrical consumption and battery authority

#81
Merged chris wants to merge codex/owned-vtol-electrical-energy into main
15 files +605 -28
resources/functions/drone/vehicles/measurements.tsmodified+37-2
Changes to resources/functions/drone/vehicles/measurements.ts
@@ -1,9 +1,36 @@
11import type { EstimatorSnapshot } from '../estimation/estimator'
2import type { VehicleKind, VehicleMeasurement } from './types'
2import type { VehicleBatteryModel, VehicleBatteryObservation, VehicleKind, VehicleMeasurement, VehicleMissionPlan } from './types'
33export function vehicleReference(estimate: EstimatorSnapshot) { return `${estimate.bootId}:${Object.values(estimate.resets).join(',')}` }
4
5/** Capture a declared source envelope before allocating a simulation session. */
6export 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. */
24export 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}
430/** Shared envelope qualification. Domain adapters still validate physical quantities and units. */
5export function createVehicleMeasurementQualifier(vehicle: VehicleKind) {
31export function createVehicleMeasurementQualifier(vehicle: VehicleKind, batteryModel?: VehicleBatteryModel) {
632 let reference: string | null = null, sequence = 0, captured = -Infinity, signature = '', now = -Infinity
33 let energyUsedWh = 0, batteryCutoff = false
734 return {
835 qualify(input: VehicleMeasurement | null, atMs: number, expectedReference: string): VehicleMeasurement | null {
936 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) {
1441 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')
1542 const encoded = JSON.stringify(m)
1643 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 }
1752 reference = m.reference; sequence = m.sequence; captured = m.capturedAtMs; signature = encoded
1853 return m
1954 },