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/game/actions.test.ts

@@ -13,9 +13,11 @@ import { HUB_ICAO } from './seed';
 import {
   abandonPackage,
   buyPlane,
+  cancelQueuedLeg,
   flyPlane,
   GameActionError,
   loadPackage,
+  queueLeg,
   refuelPlane,
   sellPlane,
 } from './actions';
@@ -206,6 +208,75 @@ describe('flyPlane', () => {
   });
 });
 
+describe('queueLeg (v0.25.0, ISS-043)', () => {
+  it('appends legs to the queue in order and persists them as JSON', async () => {
+    const inst = await freshDb('qleg-ok.db');
+
+    await queueLeg(inst, 'plane-starter', 'LEMD');
+    let plane = (await inst.db.select().from(schema.planes))[0];
+    expect(JSON.parse(plane.queue)).toEqual(['LEMD']);
+
+    await queueLeg(inst, 'plane-starter', 'EHAM'); // pre-building a route
+    plane = (await inst.db.select().from(schema.planes))[0];
+    expect(JSON.parse(plane.queue)).toEqual(['LEMD', 'EHAM']); // order preserved
+  });
+
+  it('works on a flying plane too — the active leg is untouched, nothing auto-starts', async () => {
+    const inst = await freshDb('qleg-flying.db');
+    await inst.db.update(schema.planes)
+      .set({ status: 'flying', departureSimTime: T0, destIcao: 'LEMD' })
+      .where(eq(schema.planes.id, 'plane-starter'));
+
+    await queueLeg(inst, 'plane-starter', 'EHAM');
+
+    const plane = (await inst.db.select().from(schema.planes))[0];
+    expect(plane.status).toBe('flying'); // still on its active leg…
+    expect(plane.destIcao).toBe('LEMD'); // …unchanged — queueing never starts a flight
+    expect(JSON.parse(plane.queue)).toEqual(['EHAM']);
+  });
+
+  it('rejects an unknown plane id with 404', async () => {
+    const inst = await freshDb('qleg-ghost.db');
+    await expectActionError(queueLeg(inst, 'ghost', 'LEMD'), 404);
+  });
+
+  it('rejects an ICAO not in the airport dataset with 400', async () => {
+    const inst = await freshDb('qleg-unknownicao.db');
+    await expectActionError(queueLeg(inst, 'plane-starter', 'ZZZZ'), 400, /unknown airport/);
+  });
+});
+
+describe('cancelQueuedLeg (v0.25.0, ISS-043)', () => {
+  it('removes the leg at the given index and keeps the rest in order', async () => {
+    const inst = await freshDb('qcancel-ok.db');
+    await queueLeg(inst, 'plane-starter', 'LEMD');
+    await queueLeg(inst, 'plane-starter', 'EHAM');
+    await queueLeg(inst, 'plane-starter', 'EDDV');
+
+    await cancelQueuedLeg(inst, 'plane-starter', 1); // drop EHAM (the middle leg)
+
+    const plane = (await inst.db.select().from(schema.planes))[0];
+    expect(JSON.parse(plane.queue)).toEqual(['LEMD', 'EDDV']);
+  });
+
+  it('rejects an out-of-range index with 400', async () => {
+    const inst = await freshDb('qcancel-oob.db');
+    await queueLeg(inst, 'plane-starter', 'LEMD'); // one leg → only index 0 is valid
+    await expectActionError(cancelQueuedLeg(inst, 'plane-starter', 1), 400);
+    await expectActionError(cancelQueuedLeg(inst, 'plane-starter', -1), 400);
+  });
+
+  it('rejects cancelling from an empty queue with 400', async () => {
+    const inst = await freshDb('qcancel-empty.db'); // seeded starter has no queued legs
+    await expectActionError(cancelQueuedLeg(inst, 'plane-starter', 0), 400);
+  });
+
+  it('rejects an unknown plane id with 404', async () => {
+    const inst = await freshDb('qcancel-ghost.db');
+    await expectActionError(cancelQueuedLeg(inst, 'ghost', 0), 404);
+  });
+});
+
 describe('abandonPackage', () => {
   // A loaded package created at T0 with a 10h window; the seeded sim clock is T0.
   const REWARD = 1_000;

lib/game/actions.ts

@@ -6,7 +6,7 @@ import { loadAirportsGeoJson } from '@/lib/airports';
 import { haversineKm } from '@/lib/geo';
 import { requiredFuelFor } from '@/lib/sim/movement';
 import { runAction } from '@/lib/sim/engine';
-import { getStateSnapshot } from './state';
+import { getStateSnapshot, parseIcaoQueue } from './state';
 import { FUEL_PRICE_PER_L, PLANE_TYPES, SELL_FRACTION } from './catalog';
 import { abandonPenalty } from './penalty';
 import { HUB_ICAO } from './seed';
@@ -131,6 +131,48 @@ export async function flyPlane(inst: GameDb, planeId: string, destIcao: string):
   await persist(inst);
 }
 
+// --- Queue (POST /api/planes/:id/queue {destIcao}) — ISS-043 part 1 ---
+
+// Append a NOT-yet-started leg to the plane's queue. Works whether the plane is
+// grounded or flying (you can pre-build a route); nothing auto-starts here — the
+// active leg still starts via flyPlane, and queued legs chain on landing when fuel
+// covers them (lib/sim/engine.ts deliverPackages). Validation: known plane, ICAO
+// in the airport dataset.
+export async function queueLeg(inst: GameDb, planeId: string, destIcao: string): Promise<void> {
+  const planeRows = await inst.db.select().from(schema.planes).where(eq(schema.planes.id, planeId));
+  const plane = planeRows[0];
+  if (!plane) throw new GameActionError(404, `plane ${planeId} not found`);
+
+  const fc = await loadAirportsGeoJson();
+  if (!fc.features.some((f) => f.properties.icao === destIcao)) {
+    throw new GameActionError(400, `unknown airport ${destIcao}`);
+  }
+
+  const queue = parseIcaoQueue(plane.queue);
+  queue.push(destIcao);
+  await inst.db.update(schema.planes).set({ queue: JSON.stringify(queue) }).where(eq(schema.planes.id, planeId));
+  await persist(inst);
+}
+
+// --- Queue cancel (POST /api/planes/:id/queue/cancel {index}) — ISS-043 part 1 ---
+
+// Remove a NOT-yet-started leg from the queue by index. Only queued legs are
+// cancellable — the active in-flight leg (destIcao) is never affected. Validation:
+// known plane, integer index within [0, queue.length).
+export async function cancelQueuedLeg(inst: GameDb, planeId: string, index: number): Promise<void> {
+  const planeRows = await inst.db.select().from(schema.planes).where(eq(schema.planes.id, planeId));
+  const plane = planeRows[0];
+  if (!plane) throw new GameActionError(404, `plane ${planeId} not found`);
+
+  const queue = parseIcaoQueue(plane.queue);
+  if (index < 0 || index >= queue.length) {
+    throw new GameActionError(400, `queue index ${index} out of range — the queue holds ${queue.length} legs`);
+  }
+  queue.splice(index, 1);
+  await inst.db.update(schema.planes).set({ queue: JSON.stringify(queue) }).where(eq(schema.planes.id, planeId));
+  await persist(inst);
+}
+
 // --- Abandon (POST /api/packages/:id/abandon) ---
 
 // Drop a package that is on a GROUNDED plane. Penalty = fraction of the payout

lib/game/seed.test.ts

@@ -44,6 +44,7 @@ describe('buildSeed', () => {
       destIcao: null,
       lat: 50.0333,
       lon: 8.5706,
+      queue: [], // v0.25.0 (ISS-043) — no queued legs on first run
     });
   });
 

lib/game/seed.ts

@@ -38,6 +38,9 @@ export interface SeedPlane {
   destIcao: null;
   lat: number;
   lon: number;
+  // Upcoming legs not yet started (v0.25.0, ISS-043) — serialized to the queue
+  // column as JSON text on insert; defaults to an empty queue.
+  queue?: string[];
 }
 
 export interface SeedPackage {
@@ -182,6 +185,7 @@ export function buildSeed(input: {
     destIcao: null,
     lat: hub.lat,
     lon: hub.lon,
+    queue: [], // no queued legs on first run (v0.25.0)
   };
 
   const count = PACKAGE_COUNT_MIN + Math.floor(rng() * (PACKAGE_COUNT_MAX - PACKAGE_COUNT_MIN + 1));

lib/game/state.ts

@@ -24,6 +24,21 @@ export interface PlaneState {
   departureSimTime: number | null;
   lat: number;
   lon: number;
+  // Upcoming legs NOT yet started (v0.25.0, ISS-043) — ordered ICAOs; the active
+  // leg is destIcao. The engine auto-chains queue[0] on landing when fuel covers it.
+  queue: string[];
+}
+
+// Parse the planes.queue JSON column into an ICAO list (v0.25.0). Guards against
+// null/empty/malformed values so a corrupt cell can never break a snapshot or tick.
+export function parseIcaoQueue(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const v: unknown = JSON.parse(raw);
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : [];
+  } catch {
+    return [];
+  }
 }
 
 export interface PackageState {
@@ -108,6 +123,7 @@ export async function getStateSnapshot(): Promise<StateSnapshot> {
         departureSimTime: p.departureSimTime,
         lat: live?.lat ?? p.lat,
         lon: live?.lon ?? p.lon,
+        queue: parseIcaoQueue(p.queue),
       };
     }),
     packages: packageRows.map((p) => ({