Flight queue backend: planes hold a queue of upcoming legs, auto-chain on landing (ISS-043 part 1)

- planes.queue TEXT NOT NULL DEFAULT '[]' — ordered JSON array of not-yet-started
  leg ICACs; active leg stays destIcao + departureSimTime. DDL + guarded ALTER
  migration for existing DBs; seed sets queue: [] explicitly.
- deliverPackages() auto-chains on arrival: with a non-empty queue and fuel
  covering the first queued leg (same requiredFuelFor rule as /fly), the plane
  immediately starts that leg from the arrival airport (stays 'flying',
  departureSimTime = arrival instant, queue shortened). Short tank → grounds
  safely with the queue kept intact; empty queue → unchanged grounding. Cargo
  delivery for the reached airport runs first and is unaffected. Ordering kept:
  delivery still runs before tickOnce's pause check, so a chained plane counts
  as still flying — no premature last-plane pause (ISS-041 preserved).
- New endpoints via performAction(): POST /api/planes/{planeId}/queue {destIcao}
  (append; works grounded or flying; 400 bad body/unknown ICAO, 404 unknown
  plane) and POST /api/planes/{planeId}/queue/cancel {index} (remove queued leg
  by index; active in-flight leg never affected; 400 non-integer/out-of-range,
  404 unknown plane). Both return the full state snapshot.
- PlaneState.queue: string[] in /api/state (null/malformed-safe parse helper
  shared with the engine); OpenAPI updated (PlaneState.queue, QueueLegRequest,
  CancelQueuedLegRequest, both paths) and openapi.test.ts expectations extended.
- Tests: auto-chain block in engine.test.ts (chain / short-fuel ground / empty
  queue) + chained-plane-no-pause regression guard; queueLeg/cancelQueuedLeg
  blocks in actions.test.ts; type-compat queue: [] fixtures in deriveEvents,
  right-pane, mapData and seed tests.

v0.25.0 — part 1 (backend) of ISS-043; UI/map rendering lands in a follow-up.

lib/sim/engine.ts

@@ -5,6 +5,7 @@ import * as schema from '@/lib/db/schema';
 import { loadAirportsGeoJson } from '@/lib/airports';
 import { haversineKm } from '@/lib/geo';
 import { PLANE_TYPES } from '@/lib/game/catalog';
+import { parseIcaoQueue } from '@/lib/game/state';
 import {
   generatePackage,
   MARKET_TARGET_OPEN_PACKAGES,
@@ -12,7 +13,7 @@ import {
   type Rng,
   type SeedAirport,
 } from '@/lib/game/seed';
-import { arrivalTimeFor, fuelAtWeighted } from './movement';
+import { arrivalTimeFor, fuelAtWeighted, requiredFuelFor } 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
@@ -122,12 +123,17 @@ export async function expirePackages(inst: GameDb, clockMs: number): Promise<num
 }
 
 // Finalize in-flight planes whose arrival time has passed (v0.12.0 delivery):
-// ground the plane at its dest_icao with its remaining fuel, then for every
-// package bound to it and destined for that airport — 'loaded' ones still inside
-// their deadline are delivered (cash += reward + reputation gain per package),
-// 'expired' ones just unbind (no reward). Packages destined elsewhere stay loaded
-// on the plane for a later leg. Idempotent — a finalized plane leaves the
-// 'flying' state, so it can never be awarded twice. Returns planes landed.
+// for every package bound to the plane and destined for its dest_icao — 'loaded'
+// ones still inside their deadline are delivered (cash += reward + reputation
+// gain per package), 'expired' ones just unbind (no reward). Packages destined
+// elsewhere stay loaded on the plane for a later leg. Then (v0.25.0, ISS-043)
+// auto-chain: if the queue holds legs and fuel covers the first one, start it
+// immediately from the arrival airport; otherwise ground the plane there with
+// its remaining fuel (a short tank keeps the queue intact for refuel + re-dispatch).
+// Idempotent — a finalized plane either leaves the 'flying' state or starts a NEW
+// leg whose own arrival is in the future, so it can never be awarded twice.
+// Returns planes landed. NOTE: runs BEFORE tickOnce's pause check on purpose —
+// a chained plane counts as still flying there, so chaining never pauses early.
 export async function deliverPackages(inst: GameDb, clockMs: number): Promise<number> {
   const [planeRows, packageRows] = await Promise.all([
     inst.db.select().from(schema.planes),
@@ -149,19 +155,10 @@ export async function deliverPackages(inst: GameDb, clockMs: number): Promise<nu
     if (clockMs < arrivalTimeFor(p.departureSimTime, distanceKm, type.speedKmh)) continue;
 
     // Arrived: progress is exactly 1 here, so remaining fuel is the full-leg weighted burn.
-    await inst.db.update(schema.planes)
-      .set({
-        status: 'available',
-        locationIcao: to.icao,
-        lat: to.lat,
-        lon: to.lon,
-        fuel: fuelAtWeighted(p.fuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm, 1),
-        departureSimTime: null,
-        destIcao: null,
-      })
-      .where(eq(schema.planes.id, p.id));
+    const landedFuel = fuelAtWeighted(p.fuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm, 1);
 
-    // Deliver every bound package whose destination is the airport just reached.
+    // Deliver every bound package whose destination is the airport just reached —
+    // runs whether or not a queued leg chains next (ISS-043).
     const onBoard = packageRows.filter((pk) => pk.planeId === p.id && pk.destIcao === to.icao);
     for (const pk of onBoard) {
       if (pk.status === 'loaded' && clockMs <= pk.deadlineSimTime) {
@@ -178,6 +175,47 @@ export async function deliverPackages(inst: GameDb, clockMs: number): Promise<nu
         await inst.db.update(schema.packages).set({ planeId: null }).where(eq(schema.packages.id, pk.id));
       }
     }
+
+    // Auto-chain (ISS-043): with a non-empty queue and enough fuel for the first
+    // queued leg, start it immediately from `to` — same feasibility rule as flyPlane
+    // (requiredFuelFor is independent of current load). Otherwise ground here; an
+    // unknown ICAO in the queue simply cannot chain. The remaining queue is kept
+    // intact either way so a grounded plane can refuel and re-dispatch.
+    const queue = parseIcaoQueue(p.queue);
+    let chainedTo: string | null = null;
+    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;
+      }
+    }
+    await inst.db.update(schema.planes)
+      .set(
+        chainedTo
+          ? {
+              status: 'flying',
+              locationIcao: to.icao,
+              lat: to.lat,
+              lon: to.lon,
+              fuel: landedFuel,
+              destIcao: chainedTo,
+              departureSimTime: clockMs, // the arrival instant — position is exactly `to`
+              queue: JSON.stringify(queue),
+            }
+          : {
+              status: 'available',
+              locationIcao: to.icao,
+              lat: to.lat,
+              lon: to.lon,
+              fuel: landedFuel,
+              departureSimTime: null,
+              destIcao: null,
+              queue: JSON.stringify(queue),
+            },
+      )
+      .where(eq(schema.planes.id, p.id));
     n++;
   }
   return n;