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

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest';
 import { openApiSpec } from './openapi';
 
 describe('OpenAPI spec', () => {
-  it('documents exactly the ten public endpoints (4 read + 6 player actions)', () => {
+  it('documents exactly the twelve public endpoints (4 read + 8 player actions)', () => {
     expect(Object.keys(openApiSpec.paths).sort()).toEqual([
       '/api/airports',
       '/api/market/buy-plane',
@@ -11,6 +11,8 @@ describe('OpenAPI spec', () => {
       '/api/packages/{id}/abandon',
       '/api/packages/{id}/load',
       '/api/planes/{planeId}/fly',
+      '/api/planes/{planeId}/queue', // v0.25.0 (ISS-043)
+      '/api/planes/{planeId}/queue/cancel', // v0.25.0 (ISS-043)
       '/api/planes/{planeId}/refuel',
       '/api/sim',
       '/api/state',
@@ -120,6 +122,7 @@ describe('OpenAPI spec', () => {
       'lon',
       'maxFuel',
       'model',
+      'queue', // v0.25.0 (ISS-043) — upcoming legs not yet started
       'status',
     ]);
 
@@ -169,7 +172,7 @@ describe('OpenAPI spec', () => {
     expect(Object.keys(error)).toEqual(['error']);
   });
 
-  it('documents the six action endpoints: snapshot on 200, Error on their 4xx paths', () => {
+  it('documents the eight action endpoints: snapshot on 200, Error on their 4xx paths', () => {
     // The spec object is a literal type; these helpers view it as plain JSON.
     const post = (p: string) =>
       ((openApiSpec.paths as Record<string, { post?: unknown }>)[p]?.post ?? {}) as {
@@ -183,6 +186,8 @@ describe('OpenAPI spec', () => {
       '/api/packages/{id}/load',
       '/api/packages/{id}/abandon',
       '/api/planes/{planeId}/fly',
+      '/api/planes/{planeId}/queue', // v0.25.0 (ISS-043)
+      '/api/planes/{planeId}/queue/cancel', // v0.25.0 (ISS-043)
       '/api/market/buy-plane',
       '/api/market/sell-plane',
       '/api/planes/{planeId}/refuel',
@@ -196,6 +201,8 @@ describe('OpenAPI spec', () => {
     expect(errorCodes('/api/packages/{id}/load')).toEqual(['400', '404', '409']);
     expect(errorCodes('/api/packages/{id}/abandon')).toEqual(['404', '409']);
     expect(errorCodes('/api/planes/{planeId}/fly')).toEqual(['400', '404', '409']);
+    expect(errorCodes('/api/planes/{planeId}/queue')).toEqual(['400', '404']); // v0.25.0 — no 409: queueing works grounded or flying
+    expect(errorCodes('/api/planes/{planeId}/queue/cancel')).toEqual(['400', '404']); // v0.25.0
     expect(errorCodes('/api/market/buy-plane')).toEqual(['400', '409']);
     expect(errorCodes('/api/market/sell-plane')).toEqual(['400', '404', '409']);
     expect(errorCodes('/api/planes/{planeId}/refuel')).toEqual(['400', '404', '409']); // v0.16.0 optional body
@@ -208,6 +215,12 @@ describe('OpenAPI spec', () => {
     expect(post('/api/planes/{planeId}/fly').requestBody?.content['application/json'].schema.$ref).toBe(
       '#/components/schemas/FlyPlaneRequest',
     );
+    expect(post('/api/planes/{planeId}/queue').requestBody?.content['application/json'].schema.$ref).toBe(
+      '#/components/schemas/QueueLegRequest', // v0.25.0 (ISS-043)
+    );
+    expect(post('/api/planes/{planeId}/queue/cancel').requestBody?.content['application/json'].schema.$ref).toBe(
+      '#/components/schemas/CancelQueuedLegRequest', // v0.25.0 (ISS-043)
+    );
     expect(post('/api/market/buy-plane').requestBody?.content['application/json'].schema.$ref).toBe(
       '#/components/schemas/BuyPlaneRequest',
     );
@@ -224,6 +237,8 @@ describe('OpenAPI spec', () => {
     expect(paramNames('/api/packages/{id}/load')).toEqual(['id']);
     expect(paramNames('/api/packages/{id}/abandon')).toEqual(['id']);
     expect(paramNames('/api/planes/{planeId}/fly')).toEqual(['planeId']);
+    expect(paramNames('/api/planes/{planeId}/queue')).toEqual(['planeId']); // v0.25.0 (ISS-043)
+    expect(paramNames('/api/planes/{planeId}/queue/cancel')).toEqual(['planeId']); // v0.25.0 (ISS-043)
     expect(paramNames('/api/planes/{planeId}/refuel')).toEqual(['planeId']);
 
     // Request schema shapes.
@@ -233,6 +248,13 @@ describe('OpenAPI spec', () => {
     const fly = openApiSpec.components.schemas.FlyPlaneRequest;
     expect(fly.required).toEqual(['destIcao']);
     expect(fly.properties.destIcao.type).toBe('string');
+    // v0.25.0 (ISS-043): the queue request schemas mirror fly's destIcao shape.
+    const queueLeg = openApiSpec.components.schemas.QueueLegRequest;
+    expect(queueLeg.required).toEqual(['destIcao']);
+    expect(queueLeg.properties.destIcao.type).toBe('string');
+    const cancelQueuedLeg = openApiSpec.components.schemas.CancelQueuedLegRequest;
+    expect(cancelQueuedLeg.required).toEqual(['index']);
+    expect(cancelQueuedLeg.properties.index.type).toBe('integer');
     const buy = openApiSpec.components.schemas.BuyPlaneRequest;
     expect(buy.required).toEqual(['model']);
     expect(buy.properties.model.type).toBe('string');