Maintenance: distance wear, broken-state burn ×1.5, repair action (ISS-069, v0.39.0)

lib/openapi.ts

@@ -404,6 +404,31 @@ export const openApiSpec = {
         },
       },
     },
+    '/api/planes/{planeId}/repair': {
+      post: {
+        summary: 'Repair a grounded plane',
+        description:
+          'Restore a worn-out plane to full health for the flat repair cost (v0.39.0, ISS-069): the plane is grounded in "repairing" status until 3 sim days pass, when the engine\'s tick flips it back to "available". While repairing it cannot load, fly, refuel or be sold; a broken plane (health ≤ 0) still flies but burns 50% more fuel. A full-health repair is a free no-op (cost 0). No body.',
+        operationId: 'repairPlane',
+        parameters: [
+          { name: 'planeId', in: 'path', required: true, schema: { type: 'string' } },
+        ],
+        responses: {
+          200: {
+            description: 'Repair started (or free no-op) — full state snapshot (health 100, status "repairing" with the gate set, cash reduced by the flat cost)',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/StateSnapshot' } } },
+          },
+          404: {
+            description: 'Unknown plane id',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+          },
+          409: {
+            description: 'Plane is not grounded (flying or already repairing), or cash is insufficient for the repair cost',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+          },
+        },
+      },
+    },
   },
   components: {
     schemas: {
@@ -595,7 +620,7 @@ export const openApiSpec = {
         properties: {
           id: { type: 'string' },
           model: { type: 'string' },
-          status: { enum: ['available', 'flying'] },
+          status: { enum: ['available', 'flying', 'repairing'] }, // v0.39.0 (ISS-069) — "repairing" = grounded in the shop until repairUntilSimTime passes
           fuel: { type: 'number' },
           maxFuel: { type: 'number' },
           locationIcao: { type: 'string' },
@@ -620,6 +645,16 @@ export const openApiSpec = {
             description:
               'Upcoming flight legs NOT yet started (v0.25.0) — ordered ICAOs; the active leg is destIcao. The engine auto-chains queue[0] on landing when fuel covers it.',
           },
+          health: {
+            type: 'number',
+            description:
+              'Structural health in [0, 100] (v0.39.0) — wears down by a fixed amount per km of landed legs; at 0 the plane is broken and burns 50% more fuel until repaired.',
+          },
+          repairUntilSimTime: {
+            type: ['integer', 'null'],
+            description:
+              'Sim-clock epoch ms when an active repair finishes (v0.39.0) — set with status "repairing", cleared by the engine\'s flip-back; null when not in repair.',
+          },
         },
         required: [
           'id',
@@ -635,6 +670,8 @@ export const openApiSpec = {
           'lat',
           'lon',
           'queue',
+          'health', // v0.39.0 (ISS-069) — structural health in [0, 100]
+          'repairUntilSimTime', // v0.39.0 (ISS-069) — active repair gate; null when not repairing
         ],
       },
       PackageState: {