Special jobs: data-driven special-status registry with priority status (ISS-073, v0.37.0)

lib/game/seed.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { haversineKm } from '@/lib/geo';
 import { PLANE_TYPES, STARTER_MODEL } from './catalog';
+import { SPECIALS } from './specials';
 import {
   BASE_REWARD,
   buildSeed,
@@ -71,14 +72,14 @@ describe('buildSeed', () => {
     expect(new Set(seed.packages.map((c) => c.id)).size).toBe(seed.packages.length);
   });
 
-  it('applies the reward formula: round(500 + 2.5 * km + 0.5 * weightKg)', () => {
+  it('applies the reward formula: round(500 + 2.5 * km + 0.5 * weightKg), × special multiplier', () => {
     const seed = seedWith(42);
     for (const c of seed.packages) {
       const o = AIRPORTS.find((a) => a.icao === c.originIcao)!;
       const d = AIRPORTS.find((a) => a.icao === c.destIcao)!;
-      expect(c.reward).toBe(
-        Math.round(BASE_REWARD + REWARD_PER_KM * haversineKm(o.lat, o.lon, d.lat, d.lon) + REWARD_PER_KG * c.weightKg),
-      );
+      // v0.37.0 (ISS-073): special packages pay the registry multiplier on top of the base formula.
+      const mult = c.special ? SPECIALS[c.special]?.rewardMultiplier ?? 1 : 1;
+      expect(c.reward).toBe(Math.round(rewardFor(haversineKm(o.lat, o.lon, d.lat, d.lon), c.weightKg) * mult));
     }
   });
 
@@ -94,11 +95,13 @@ describe('buildSeed', () => {
     }
   });
 
-  it('sets deadlines inside the 6–72h game-time window after now', () => {
+  it('sets deadlines inside the 6–72h game-time window after now (scaled by any special status)', () => {
     const seed = seedWith(42);
     for (const c of seed.packages) {
-      expect(c.deadlineSimTime).toBeGreaterThan(NOW + 6 * 3_600_000 - 1);
-      expect(c.deadlineSimTime).toBeLessThanOrEqual(NOW + 72 * 3_600_000);
+      // v0.37.0 (ISS-073): a special's deadlineScale tightens the drawn window (e.g. priority → 3–36h).
+      const scale = c.special ? SPECIALS[c.special]?.deadlineScale ?? 1 : 1;
+      expect(c.deadlineSimTime).toBeGreaterThan(NOW + 6 * 3_600_000 * scale - 1);
+      expect(c.deadlineSimTime).toBeLessThanOrEqual(NOW + 72 * 3_600_000 * scale);
     }
   });
 
@@ -143,13 +146,14 @@ describe('generatePackage (shared seed/spawn builder)', () => {
 
     const o = AIRPORTS.find((a) => a.icao === c.originIcao)!;
     const d = AIRPORTS.find((a) => a.icao === c.destIcao)!;
-    expect(c.reward).toBe(
-      Math.round(BASE_REWARD + REWARD_PER_KM * haversineKm(o.lat, o.lon, d.lat, d.lon) + REWARD_PER_KG * c.weightKg),
-    );
+    // v0.37.0 (ISS-073): special packages pay the registry multiplier on top of the base formula.
+    const mult = c.special ? SPECIALS[c.special]?.rewardMultiplier ?? 1 : 1;
+    expect(c.reward).toBe(Math.round(rewardFor(haversineKm(o.lat, o.lon, d.lat, d.lon), c.weightKg) * mult));
 
-    // Same 6–72h game-time deadline window as the seed.
-    expect(c.deadlineSimTime).toBeGreaterThan(NOW + 6 * 3_600_000 - 1);
-    expect(c.deadlineSimTime).toBeLessThanOrEqual(NOW + 72 * 3_600_000);
+    // Same 6–72h game-time deadline window as the seed — scaled by any special status.
+    const scale = c.special ? SPECIALS[c.special]?.deadlineScale ?? 1 : 1;
+    expect(c.deadlineSimTime).toBeGreaterThan(NOW + 6 * 3_600_000 * scale - 1);
+    expect(c.deadlineSimTime).toBeLessThanOrEqual(NOW + 72 * 3_600_000 * scale);
   });
 
   it('is deterministic for a fixed RNG and honors the id/nowMs inputs', () => {
@@ -191,9 +195,9 @@ describe('generatePackage (shared seed/spawn builder)', () => {
 
       const o = AIRPORTS.find((a) => a.icao === c.originIcao)!;
       const d = AIRPORTS.find((a) => a.icao === c.destIcao)!;
-      expect(c.reward).toBe(
-        Math.round(BASE_REWARD + REWARD_PER_KM * haversineKm(o.lat, o.lon, d.lat, d.lon) + REWARD_PER_KG * c.weightKg),
-      );
+      // v0.37.0 (ISS-073): the rolled special (if any) multiplies the base reward.
+      const mult = c.special ? SPECIALS[c.special]?.rewardMultiplier ?? 1 : 1;
+      expect(c.reward).toBe(Math.round(rewardFor(haversineKm(o.lat, o.lon, d.lat, d.lon), c.weightKg) * mult));
     });
 
     it('destIcao forces the destination; origin stays random but distinct', () => {
@@ -209,9 +213,9 @@ describe('generatePackage (shared seed/spawn builder)', () => {
 
       const o = AIRPORTS[0]; // EDDF
       const d = AIRPORTS[1]; // EHAM
-      expect(c.reward).toBe(
-        Math.round(BASE_REWARD + REWARD_PER_KM * haversineKm(o.lat, o.lon, d.lat, d.lon) + REWARD_PER_KG * c.weightKg),
-      );
+      // v0.37.0 (ISS-073): the rolled special (if any) multiplies the base reward.
+      const mult = c.special ? SPECIALS[c.special]?.rewardMultiplier ?? 1 : 1;
+      expect(c.reward).toBe(Math.round(rewardFor(haversineKm(o.lat, o.lon, d.lat, d.lon), c.weightKg) * mult));
     });
 
     it('is deterministic for a fixed RNG with forced endpoints', () => {
@@ -242,7 +246,9 @@ describe('generatePackage (shared seed/spawn builder)', () => {
 
       const o = AIRPORTS.find((a) => a.icao === c.originIcao)!;
       const d = AIRPORTS.find((a) => a.icao === c.destIcao)!;
-      expect(c.reward).toBe(Math.round(BASE_REWARD + REWARD_PER_KM * haversineKm(o.lat, o.lon, d.lat, d.lon) + REWARD_PER_KG * 1_234));
+      // v0.37.0 (ISS-073): the rolled special (if any) multiplies the base reward.
+      const mult = c.special ? SPECIALS[c.special]?.rewardMultiplier ?? 1 : 1;
+      expect(c.reward).toBe(Math.round(rewardFor(haversineKm(o.lat, o.lon, d.lat, d.lon), 1_234) * mult));
 
       // Deterministic for a fixed RNG…
       const again = generatePackage({ id: 'c-w', airports: AIRPORTS, rng: mulberry32(42), nowMs: NOW, weightKg: 1_234 });
@@ -252,4 +258,44 @@ describe('generatePackage (shared seed/spawn builder)', () => {
       expect(c.deadlineSimTime).not.toBe(unforced.deadlineSimTime);
     });
   });
+
+  describe('special status (v0.37.0, ISS-073)', () => {
+    it('a forced special passes through; an explicit null forces none; omitted rolls a registry key or null', () => {
+      const base = { id: 'c-sp', airports: AIRPORTS, nowMs: NOW };
+      expect(generatePackage({ ...base, rng: mulberry32(42), special: 'priority' }).special).toBe('priority');
+      expect(generatePackage({ ...base, rng: mulberry32(42), special: null }).special).toBeNull();
+      const rolled = generatePackage({ ...base, rng: mulberry32(42) });
+      expect(rolled.special === null || SPECIALS[rolled.special] !== undefined).toBe(true);
+    });
+
+    it('applies the registry reward multiplier to the base reward', () => {
+      const c = generatePackage({ id: 'c-sp-r', airports: AIRPORTS, rng: mulberry32(42), nowMs: NOW, originIcao: 'EDDF', destIcao: 'EHAM', weightKg: 1_000, special: 'priority' });
+      const km = haversineKm(AIRPORTS[0].lat, AIRPORTS[0].lon, AIRPORTS[1].lat, AIRPORTS[1].lon); // EDDF → EHAM
+      expect(c.reward).toBe(Math.round(rewardFor(km, 1_000) * SPECIALS.priority.rewardMultiplier));
+    });
+
+    it('scales the drawn deadline window by the registry factor', () => {
+      const c = generatePackage({ id: 'c-sp-d', airports: AIRPORTS, rng: mulberry32(42), nowMs: NOW, special: 'priority' });
+      expect(c.deadlineSimTime).toBeGreaterThan(NOW + 6 * 3_600_000 * SPECIALS.priority.deadlineScale - 1);
+      expect(c.deadlineSimTime).toBeLessThanOrEqual(NOW + 72 * 3_600_000 * SPECIALS.priority.deadlineScale);
+    });
+
+    it('a forced deadline offset skips the special scaling', () => {
+      const c = generatePackage({ id: 'c-sp-f', airports: AIRPORTS, rng: mulberry32(42), nowMs: NOW, special: 'priority', deadlineOffsetMs: 10_000 });
+      expect(c.deadlineSimTime).toBe(NOW + 10_000); // forced offset untouched by the scale
+    });
+
+    it('a forced special (including explicit null) skips the appended RNG draw', () => {
+      const countDraws = (special?: string | null): number => {
+        let n = 0;
+        const base = mulberry32(42);
+        generatePackage({ id: 'c-sp-n', airports: AIRPORTS, rng: () => { n += 1; return base(); }, nowMs: NOW, special });
+        return n;
+      };
+      // origin, dest, cargoType, cargoCount, weight jitter, deadline window — the fixed order minus the appended draw.
+      expect(countDraws('priority')).toBe(6);
+      expect(countDraws(null)).toBe(6); // explicit null skips too
+      expect(countDraws()).toBeGreaterThanOrEqual(7); // pickSpecial draws 1–2 extra
+    });
+  });
 });

lib/game/seed.ts

@@ -1,5 +1,6 @@
 import { haversineKm } from '@/lib/geo';
 import { PLANE_TYPES, STARTER_MODEL } from './catalog';
+import { pickSpecial, SPECIALS } from './specials';
 
 // First-run seed. Everything here is a pure function of (airports, rng, nowMs)
 // so it is fully deterministic and unit-testable: the RNG is injected, never
@@ -52,6 +53,8 @@ export interface SeedPackage {
   cargoCount: number;
   // Package weight in kg (v0.27.0, ISS-045) — unit weight × count with ±30% jitter.
   weightKg: number;
+  // Special status (v0.37.0, ISS-073) — key into lib/game/specials.ts SPECIALS; null = none.
+  special: string | null;
   deadlineSimTime: number;
   status: 'open';
   planeId: null;
@@ -116,12 +119,14 @@ export function rewardFor(km: number, weightKg: number): number {
 // weight = unit weight × count with ±30% jitter (v0.27.0), deadline now + 6–72h
 // game time (or now + deadlineOffsetMs when given — used by the e2e test hook to
 // force a near-term expiry). The RNG call order per package is fixed: origin,
-// dest, cargoType, cargoCount, weight jitter, [deadline window].
+// dest, cargoType, cargoCount, weight jitter, [deadline window], [special].
 // v0.8.0: originIcao/destIcao optionally FORCE an endpoint (spawn coverage rule +
 // the e2e create-package hook); a forced endpoint consumes no RNG draws, so
 // callers that omit both get byte-identical behavior to before.
 // v0.27.0: weightKg optionally FORCES the package weight (e2e hook) — it skips the
 // jitter draw, same pattern as forced endpoints.
+// v0.37.0 (ISS-073): special optionally FORCES the special status (string or explicit null) —
+// it skips the appended pickSpecial draw; otherwise ~SPECIAL_SPAWN_CHANCE of packages roll one.
 export function generatePackage(input: {
   id: string;
   airports: SeedAirport[];
@@ -131,6 +136,7 @@ export function generatePackage(input: {
   originIcao?: string;
   destIcao?: string;
   weightKg?: number;
+  special?: string | null;
 }): SeedPackage {
   const { airports, rng, nowMs } = input;
   if (airports.length < 2) throw new Error('package generation needs at least two airports');
@@ -165,17 +171,25 @@ export function generatePackage(input: {
   // Weight (v0.27.0): unit weight × count with ±30% jitter, integer kg — drawn AFTER
   // cargoCount so the fixed RNG order above holds; a forced weightKg skips the draw.
   const weightKg = input.weightKg ?? Math.round(UNIT_WEIGHT_KG[cargoType] * cargoCount * (0.7 + 0.6 * rng()));
-  const deadlineMs =
-    input.deadlineOffsetMs ?? (DEADLINE_MIN_HOURS + rng() * (DEADLINE_MAX_HOURS - DEADLINE_MIN_HOURS)) * 3_600_000;
+  // Drawn deadline window — the existing draw, position unchanged; special scaling is applied
+  // below AFTER the appended special draw so the fixed order above holds.
+  const drawnWindowMs = (DEADLINE_MIN_HOURS + rng() * (DEADLINE_MAX_HOURS - DEADLINE_MIN_HOURS)) * 3_600_000;
+  // v0.37.0 (ISS-073): special status — the appended draw at the END of the fixed order above; a
+  // forced value (including explicit null) skips it, same pattern as the other overrides.
+  const special = input.special !== undefined ? input.special : pickSpecial(rng);
+  const mods = special !== null ? SPECIALS[special] : undefined;
+  // Forced deadlines skip the special scaling — consistent with overrides skipping draws.
+  const deadlineMs = input.deadlineOffsetMs ?? drawnWindowMs * (mods?.deadlineScale ?? 1);
 
   return {
     id: input.id,
     originIcao: origin.icao,
     destIcao: dest.icao,
-    reward: rewardFor(km, weightKg),
+    reward: Math.round(rewardFor(km, weightKg) * (mods?.rewardMultiplier ?? 1)),
     cargoType,
     cargoCount,
     weightKg,
+    special,
     deadlineSimTime: Math.round(nowMs + deadlineMs),
     status: 'open',
     planeId: null,

lib/game/specials.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { mulberry32, type Rng } from './seed';
+import { pickSpecial, SPECIALS, SPECIAL_SPAWN_CHANCE } from './specials';
+
+describe('pickSpecial (v0.37.0, ISS-073)', () => {
+  it('returns null when the chance draw fails and consumes exactly one draw', () => {
+    let draws = 0;
+    const rng: Rng = () => { draws += 1; return 0.9; }; // ≥ SPECIAL_SPAWN_CHANCE → no special
+    expect(pickSpecial(rng)).toBeNull();
+    expect(draws).toBe(1);
+  });
+
+  it('picks among the registry keys when the chance draw passes', () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 2_000; i++) {
+      let call = 0;
+      // First call is the chance draw (< chance → roll); later calls sweep [0, 1) as index draws.
+      const rng: Rng = () => (call++ === 0 ? 0.1 : i / 2_000);
+      const s = pickSpecial(rng);
+      if (s !== null) seen.add(s);
+    }
+    expect([...seen].sort()).toEqual(Object.keys(SPECIALS).sort()); // every key reachable
+  });
+
+  it('never returns a status whose entry was removed; an empty registry consumes no draws', () => {
+    const withoutPriority = Object.fromEntries(Object.entries(SPECIALS).filter(([k]) => k !== 'priority'));
+    for (let i = 0; i < 500; i++) {
+      expect(pickSpecial(mulberry32(i), withoutPriority)).not.toBe('priority'); // removing an entry disables it
+    }
+    let draws = 0;
+    const rng: Rng = () => { draws += 1; return 0.0; }; // would pass the chance draw if consulted
+    expect(pickSpecial(rng, {})).toBeNull();
+    expect(draws).toBe(0);
+  });
+
+  it('rolls a special for roughly SPECIAL_SPAWN_CHANCE of packages (fixed RNG)', () => {
+    const rng = mulberry32(42);
+    let hits = 0;
+    for (let i = 0; i < 10_000; i++) if (pickSpecial(rng) !== null) hits++;
+    expect(hits / 10_000).toBeGreaterThan(SPECIAL_SPAWN_CHANCE - 0.05);
+    expect(hits / 10_000).toBeLessThan(SPECIAL_SPAWN_CHANCE + 0.05);
+  });
+});

lib/game/specials.ts

@@ -0,0 +1,34 @@
+// Special-status registry (v0.37.0, ISS-073) — data-driven package modifiers: one entry per
+// special status maps to reward/deadline/reputation tweaks applied at generation and delivery.
+// Adding or removing a special is an edit of ONE entry here — no scattered branches elsewhere.
+import type { Rng } from './seed';
+
+export interface SpecialModifiers {
+  // Multiplier on the base reward (applied at package generation).
+  rewardMultiplier: number;
+  // Scale factor on the drawn deadline window (applied at generation; forced offsets skip it).
+  deadlineScale: number;
+  // Flat reputation bonus added to the distance-based gain at delivery.
+  repBonus: number;
+}
+
+export const SPECIALS: Record<string, SpecialModifiers> = {
+  priority: {
+    rewardMultiplier: 1.5, // ponytail: balance-tunable — a 50% premium for the tighter deadline below
+    deadlineScale: 0.5, // ponytail: balance-tunable — half the normal 6–72h window (3–36h)
+    repBonus: 0.5, // ponytail: balance-tunable — flat rep on top of the distance-based gain at delivery
+  },
+};
+
+// Fraction of generated packages that roll a special status (v0.37.0).
+export const SPECIAL_SPAWN_CHANCE = 0.15;
+
+// Pure spawn helper: one chance draw, then a uniform pick among the registry's keys. The registry
+// is a PARAM defaulting to the real one so tests can pass a filtered/empty record — removing an
+// entry cleanly disables that status (an empty registry consumes no draws at all).
+export function pickSpecial(rng: Rng, registry: Record<string, SpecialModifiers> = SPECIALS): string | null {
+  const keys = Object.keys(registry);
+  if (keys.length === 0) return null;
+  if (rng() >= SPECIAL_SPAWN_CHANCE) return null;
+  return keys[Math.floor(rng() * keys.length)];
+}

lib/game/state.ts

@@ -53,6 +53,8 @@ export interface PackageState {
   cargoCount: number;
   // Package weight in kg (v0.27.0, ISS-045) — drives load validation + per-kg payout.
   weightKg: number;
+  // Special status (v0.37.0, ISS-073) — key into lib/game/specials.ts SPECIALS; null = none.
+  special: string | null;
   deadlineSimTime: number;
   // 'ignored' (v0.29.0, ISS-047 part B) = a dismissed open job — terminal, leaves the market.
   status: 'open' | 'loaded' | 'delivered' | 'expired' | 'abandoned' | 'ignored';
@@ -150,6 +152,7 @@ export async function getStateSnapshot(): Promise<StateSnapshot> {
       cargoType: p.cargoType,
       cargoCount: p.cargoCount,
       weightKg: p.weightKg,
+      special: p.special,
       deadlineSimTime: p.deadlineSimTime,
       status: p.status,
       planeId: p.planeId,