Wind-adjusted fuel burn ±20% + refuel-for-flight buys 150% margin (ISS-070, ISS-071, v0.36.0)

lib/sim/engine.test.ts

@@ -6,10 +6,11 @@ import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { openGameDb } from '@/lib/db/client';
 import * as schema from '@/lib/db/schema';
 import { loadAirportsGeoJson } from '@/lib/airports';
-import { haversineKm } from '@/lib/geo';
+import { haversineKm, initialBearingDeg } from '@/lib/geo';
+import { weatherFor } from '@/lib/weather';
 import { PLANE_TYPES } from '@/lib/game/catalog';
 import { MARKET_TARGET_OPEN_PACKAGES, mulberry32 } from '@/lib/game/seed';
-import { arrivalTimeFor, fuelAtWeighted, requiredFuelFor } from './movement';
+import { arrivalTimeFor, fuelAtWeighted, requiredFuelFor, windBurnFactor } from './movement';
 import {
   clampTimeScale,
   deliverPackages,
@@ -165,7 +166,7 @@ describe('deliverPackages (v0.12.0 arrival delivery)', () => {
   });
 
   it('delivers in-deadline cargo, unbinds expired cargo for free, keeps other-dest cargo bound', async () => {
-    const { inst, to, km, type } = await setupFlight('deliver-mixed.db');
+    const { inst, from, to, km, type } = await setupFlight('deliver-mixed.db');
     const accountBefore = (await inst.db.select().from(schema.account))[0]!;
 
     // Three packages on the plane: one in-deadline for TO, one expired for TO,
@@ -184,8 +185,11 @@ describe('deliverPackages (v0.12.0 arrival delivery)', () => {
     expect(plane.locationIcao).toBe(TO);
     expect(plane.lat).toBe(to.lat);
     expect(plane.lon).toBe(to.lon);
-    // Remaining fuel per the v0.16.0 weight-proportional burn model (closed form).
-    expect(plane.fuel).toBeCloseTo(fuelAtWeighted(type.maxFuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, km, 1), 6);
+    // Remaining fuel per the v0.16.0 weight-proportional burn model (closed form), wind-adjusted
+    // (v0.36.0) by the departure airport's weather vs the route heading.
+    const w = weatherFor(FROM);
+    const f = windBurnFactor(w.windKt, w.windDirDeg, initialBearingDeg(from.lat, from.lon, to.lat, to.lon));
+    expect(plane.fuel).toBeCloseTo(fuelAtWeighted(type.maxFuel, type.burnPerKm * f, type.emptyWeightKg, type.maxFuel, km, 1), 6);
     expect(plane.departureSimTime).toBeNull();
     expect(plane.destIcao).toBeNull(); // flight context cleared on landing
 
@@ -241,14 +245,19 @@ describe('deliverPackages (v0.12.0 arrival delivery)', () => {
   // --- Auto-chain on landing (v0.25.0, ISS-043) ---
 
   it('auto-chains to the next queued leg when fuel covers it', async () => {
-    const { inst, to, km, type } = await setupFlight('chain-ok.db'); // full tank EDDF→LEMD
+    const { inst, from, to, km, type } = await setupFlight('chain-ok.db'); // full tank EDDF→LEMD
     const fc = await loadAirportsGeoJson();
     const nextP = fc.features.find((f) => f.properties.icao === 'EHAM')!.properties;
     const nextKm = haversineKm(to.lat, to.lon, nextP.lat, nextP.lon);
 
-    // Precondition sanity: a full-tank departure leaves enough for the LEMD→EHAM hop.
-    const landedFuel = fuelAtWeighted(type.maxFuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, km, 1);
-    expect(requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, nextKm)).toBeLessThanOrEqual(landedFuel);
+    // Precondition sanity: a full-tank departure leaves enough for the LEMD→EHAM hop — both legs
+    // wind-adjusted (v0.36.0) exactly as deliverPackages computes them.
+    const wFrom = weatherFor(FROM);
+    const fOut = windBurnFactor(wFrom.windKt, wFrom.windDirDeg, initialBearingDeg(from.lat, from.lon, to.lat, to.lon));
+    const landedFuel = fuelAtWeighted(type.maxFuel, type.burnPerKm * fOut, type.emptyWeightKg, type.maxFuel, km, 1);
+    const wTo = weatherFor(TO); // the chained leg departs from the arrival airport
+    const fNext = windBurnFactor(wTo.windKt, wTo.windDirDeg, initialBearingDeg(to.lat, to.lon, nextP.lat, nextP.lon));
+    expect(requiredFuelFor(type.burnPerKm * fNext, type.emptyWeightKg, type.maxFuel, nextKm)).toBeLessThanOrEqual(landedFuel);
 
     await inst.db.update(schema.planes)
       .set({ queue: JSON.stringify(['EHAM', 'EDDV']) })
@@ -268,14 +277,14 @@ describe('deliverPackages (v0.12.0 arrival delivery)', () => {
   });
 
   it('grounds when fuel cannot cover the next queued leg, keeping the queue intact', async () => {
-    const { inst, km, type } = await setupFlight('chain-nofuel.db');
-    const fc = await loadAirportsGeoJson();
-    const nextP = fc.features.find((f) => f.properties.icao === 'EHAM')!.properties;
+    const { inst, from, to, km, type } = await setupFlight('chain-nofuel.db');
 
-    // Depart with exactly the fuel for EDDF→LEMD → lands empty, cannot start LEMD→EHAM.
+    // Depart with exactly the wind-adjusted fuel for EDDF→LEMD (v0.36.0) → lands empty, cannot start LEMD→EHAM.
+    const w = weatherFor(FROM);
+    const f = windBurnFactor(w.windKt, w.windDirDeg, initialBearingDeg(from.lat, from.lon, to.lat, to.lon));
     await inst.db.update(schema.planes)
       .set({
-        fuel: requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, km),
+        fuel: requiredFuelFor(type.burnPerKm * f, type.emptyWeightKg, type.maxFuel, km),
         queue: JSON.stringify(['EHAM']),
       })
       .where(eq(schema.planes.id, 'plane-starter'));

lib/sim/engine.ts

@@ -3,7 +3,8 @@ import { eq, inArray } from 'drizzle-orm';
 import { getGameDb, persist, type GameDb } from '@/lib/db/client';
 import * as schema from '@/lib/db/schema';
 import { loadAirportsGeoJson } from '@/lib/airports';
-import { haversineKm } from '@/lib/geo';
+import { haversineKm, initialBearingDeg } from '@/lib/geo';
+import { weatherFor } from '@/lib/weather';
 import { PLANE_TYPES } from '@/lib/game/catalog';
 import { parseIcaoQueue } from '@/lib/game/state';
 import {
@@ -13,7 +14,7 @@ import {
   type Rng,
   type SeedAirport,
 } from '@/lib/game/seed';
-import { arrivalTimeFor, fuelAtWeighted, requiredFuelFor } from './movement';
+import { arrivalTimeFor, fuelAtWeighted, requiredFuelFor, windBurnFactor } from './movement';
 
 // Server-authoritative sim engine (v0.7.0) — tick-on-read: there is NO background
 // timer. Every read/action endpoint calls tickNow() first; the clock advances by
@@ -156,8 +157,17 @@ export async function deliverPackages(inst: GameDb, clockMs: number): Promise<nu
     const distanceKm = haversineKm(from.lat, from.lon, to.lat, to.lon);
     if (clockMs < arrivalTimeFor(p.departureSimTime, distanceKm, type.speedKmh)) continue;
 
-    // Arrived: progress is exactly 1 here, so remaining fuel is the full-leg weighted burn.
-    const landedFuel = fuelAtWeighted(p.fuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm, 1);
+    // Arrived: progress is exactly 1 here, so remaining fuel is the full-leg weighted burn —
+    // wind-adjusted (v0.36.0) by departure weather vs route heading, same factor flyPlane used.
+    const w = weatherFor(p.locationIcao);
+    const landedFuel = fuelAtWeighted(
+      p.fuel,
+      type.burnPerKm * windBurnFactor(w.windKt, w.windDirDeg, initialBearingDeg(from.lat, from.lon, to.lat, to.lon)),
+      type.emptyWeightKg,
+      type.maxFuel,
+      distanceKm,
+      1,
+    );
 
     // Deliver every bound package whose destination is the airport just reached —
     // runs whether or not a queued leg chains next (ISS-043).
@@ -188,9 +198,19 @@ export async function deliverPackages(inst: GameDb, clockMs: number): Promise<nu
     if (queue.length > 0) {
       const nextDest = queue[0];
       const next = byIcao.get(nextDest); // unknown ICAO in the queue → cannot chain
-      if (next && requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, haversineKm(to.lat, to.lon, next.lat, next.lon)) <= landedFuel) {
-        queue.shift();
-        chainedTo = nextDest;
+      if (next) {
+        // Wind-adjusted requirement for the NEXT leg — it departs from `to` (v0.36.0).
+        const wNext = weatherFor(to.icao);
+        const nextRequiredL = requiredFuelFor(
+          type.burnPerKm * windBurnFactor(wNext.windKt, wNext.windDirDeg, initialBearingDeg(to.lat, to.lon, next.lat, next.lon)),
+          type.emptyWeightKg,
+          type.maxFuel,
+          haversineKm(to.lat, to.lon, next.lat, next.lon),
+        );
+        if (nextRequiredL <= landedFuel) {
+          queue.shift();
+          chainedTo = nextDest;
+        }
       }
     }
     await inst.db.update(schema.planes)

lib/sim/movement.test.ts

@@ -10,6 +10,7 @@ import {
   progressAt,
   requiredFuelFor,
   travelDurationMs,
+  windBurnFactor,
 } from './movement';
 
 // Synthetic in-flight fixtures — no DB needed: everything is a pure function of
@@ -166,6 +167,53 @@ describe('weighted burn model (v0.16.0)', () => {
   });
 });
 
+describe('windBurnFactor (v0.36.0, ISS-070)', () => {
+  it('full headwind at max wind is exactly +20%', () => {
+    // bearing == windDirDeg: the wind blows straight from ahead.
+    expect(windBurnFactor(30, 90, 90)).toBe(1.2);
+  });
+
+  it('full tailwind at max wind is exactly −20%', () => {
+    // windDirDeg = bearing + 180 (mod 360): the wind blows from behind.
+    expect(windBurnFactor(30, 270, 90)).toBe(0.8);
+  });
+
+  it('a pure crosswind (90° off) leaves burn unchanged', () => {
+    expect(windBurnFactor(30, 0, 90)).toBeCloseTo(1, 9);
+    expect(windBurnFactor(30, 180, 90)).toBeCloseTo(1, 9);
+  });
+
+  it('small wind stays near 1', () => {
+    const f = windBurnFactor(2, 45, 45); // worst case: full headwind at min wind
+    expect(f).toBeGreaterThan(1.01);
+    expect(f).toBeLessThan(1.02);
+  });
+
+  it('stays within [0.8, 1.2] for the whole weather range', () => {
+    for (const kt of [2, 15, 30]) {
+      for (const off of [0, 45, 90, 135, 180, 270, 315]) {
+        const f = windBurnFactor(kt, 100, (100 + off) % 360);
+        expect(f).toBeGreaterThanOrEqual(0.8 - 1e-12);
+        expect(f).toBeLessThanOrEqual(1.2 + 1e-12);
+      }
+    }
+  });
+
+  it('applied as burnPerKm × f, requiredFuelFor and fuelAtWeighted scale accordingly (pinned)', () => {
+    // Fixed inputs: ATR numbers, 1000 km leg / half of the FRA→MAD leg.
+    expect(requiredFuelFor(BURN * 1.2, WE, TANK, 1_000)).toBeCloseTo(1444.911589, 6);
+    expect(requiredFuelFor(BURN * 0.8, WE, TANK, 1_000)).toBeCloseTo(944.348095, 6);
+    expect(fuelAtWeighted(TANK, BURN * 1.2, WE, TANK, KM, 0.5)).toBeCloseTo(4867.313136, 6);
+    expect(fuelAtWeighted(TANK, BURN * 0.8, WE, TANK, KM, 0.5)).toBeCloseTo(5331.677856, 6);
+
+    // Headwind always costs more than tailwind over the same leg…
+    expect(requiredFuelFor(BURN * 1.2, WE, TANK, KM)).toBeGreaterThan(requiredFuelFor(BURN * 0.8, WE, TANK, KM));
+    expect(fuelAtWeighted(TANK, BURN * 1.2, WE, TANK, KM, 1)).toBeLessThan(fuelAtWeighted(TANK, BURN * 0.8, WE, TANK, KM, 1));
+    // …and a neutral factor (f = 1) reproduces the unadjusted model exactly.
+    expect(requiredFuelFor(BURN * windBurnFactor(30, 0, 90), WE, TANK, KM)).toBeCloseTo(requiredFuelFor(BURN, WE, TANK, KM), 9);
+  });
+});
+
 describe('maxRangeKm (v0.28.0)', () => {
   it('ATR 72-600 full tank ≈ 4439 km (±5%)', () => {
     const r = maxRangeKm(BURN, WE, TANK);

lib/sim/movement.ts

@@ -119,6 +119,15 @@ export function requiredFuelFor(
   return (emptyWeightKg / rho) * (Math.exp(k * rho * distanceKm) - 1);
 }
 
+// Wind adjustment to per-km burn (v0.36.0, ISS-070): the headwind component of a wind blowing
+// FROM `windDirDeg` against a leg heading `bearingDeg`, as a multiplier on burnPerKm —
+// factor = 1 + headwindKt/150, exactly [0.8, 1.2] over the weather range 2–30 kt (±20%).
+// Pure; callers apply it as burnPerKm * factor so every call site agrees on one value per leg.
+export function windBurnFactor(windKt: number, windDirDeg: number, bearingDeg: number): number {
+  const headwindKt = windKt * Math.cos(((bearingDeg - windDirDeg) * Math.PI) / 180);
+  return 1 + headwindKt / 150;
+}
+
 // Max range from a FULL tank under the weighted model — solve requiredFuelFor(d) = maxFuel for d:
 //   (We/ρ)(e^{kρd} − 1) = F  →  d = ln(1 + ρF/We) · (We + ρF)/(ρ·burnPerKm).
 // Returns raw km (call sites round); zero fuel gives exactly 0. Pure — display-only, the sim