From 7d49f18cc64a975fa260a0b32650ec640bd51281 Mon Sep 17 00:00:00 2001
From: itsrubberduck <frappes_remoter.2e@icloud.com>
Date: Thu, 16 Jul 2026 17:46:52 +0200
Subject: [PATCH] feat(live-atc): add simulated AI background traffic on the
 tuned frequency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements the ai-traffic roadmap item per
docs/plans/2026-07-14-ai-traffic-architecture-design.md.

Simulated other aircraft on the user's frequency — callsigns, ATC
instructions, readbacks in their own stable voice, handovers — as pure
scenery. It never touches radioBackend: the Python backend keeps owning
the dialogue *with* the user, useAiTraffic owns the radio *around* the
user. The two share only the speech queue (arbitration) and the log.

Rules live as pure, seeded, framework-free modules under
shared/utils/aiTraffic/ so they run in tsx --test without a browser:
callsign collision rules, wake/in-trail separation, runway slots, the
speed ladder, direct validation, the §3 decision table, and the gating
chain. app/composables/useAiTraffic.ts wires them to Vue (1 Hz tick,
spawner, scheduler).

Gating is evaluated twice — before enqueue and again at playback, since
seconds pass in between. Traffic never keys up while the user holds PTT,
while their transmission is out at the backend, or inside the fresh
readback window. Off by default; the toggle surfaces the feature's v1
limitations rather than burying them in a doc.

Zero LLM calls: variance comes from seeded RNG over template variants.

Deviations from the design, both documented in the design doc:
- Adds SimAircraft.quietUntilSec. The design's rule table says "first
  matching row per tick" but never says an instruction must be allowed to
  take effect before the next one. Without it the planner re-derives the
  same unresolved condition every second and nags one aircraft with the
  same vector: 624 calls/30min measured, vs 90 with the cooldown.
- Airline pool limited to the 14 designators DEFAULT_AIRLINE_TELEPHONY
  already knows; UAE/AUA/WZZ from the design would be spelled out letter
  by letter instead of spoken as airline names.

Verified: 406 tests pass (176 new), no new typecheck errors, /live-atc
compiles and serves. The manual in-session walkthrough (audible traffic,
toggle mid-session) is NOT verified — it needs a login and the Python
backend. The 30-minute deterministic integration run stands in for it and
caught two of the three bugs found during development.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../live-atc/cockpit/SettingsSheet.vue        |  69 +++
 app/composables/useAiTraffic.ts               | 456 +++++++++++++++
 app/composables/useLiveAtcSession.ts          |  14 +-
 app/composables/useRadioSpeech.ts             |  31 +-
 app/composables/useSessionState.ts            |   4 +
 app/pages/live-atc.vue                        |  54 ++
 shared/data/simAircraftTypes.ts               |  57 ++
 shared/data/trafficTiers.ts                   | 102 ++++
 shared/utils/aiTraffic/callsign.ts            | 194 +++++++
 shared/utils/aiTraffic/gating.ts              |  99 ++++
 shared/utils/aiTraffic/instructions.ts        | 549 ++++++++++++++++++
 shared/utils/aiTraffic/rng.ts                 |  72 +++
 shared/utils/aiTraffic/separation.ts          | 137 +++++
 shared/utils/aiTraffic/sim.ts                 | 213 +++++++
 shared/utils/aiTraffic/types.ts               |  50 ++
 shared/utils/communicationsEngine.ts          |   9 +-
 shared/utils/voicePool.ts                     |  68 +++
 tests/shared/aiTrafficCallsign.test.ts        | 250 ++++++++
 tests/shared/aiTrafficGating.test.ts          | 205 +++++++
 tests/shared/aiTrafficInstructions.test.ts    | 424 ++++++++++++++
 tests/shared/aiTrafficIntegration.test.ts     | 271 +++++++++
 tests/shared/aiTrafficSeparation.test.ts      | 193 ++++++
 tests/shared/aiTrafficSim.test.ts             | 257 ++++++++
 tests/shared/trafficTiers.test.ts             | 104 ++++
 tests/shared/voicePool.test.ts                |  89 +++
 25 files changed, 3968 insertions(+), 3 deletions(-)
 create mode 100644 app/composables/useAiTraffic.ts
 create mode 100644 shared/data/simAircraftTypes.ts
 create mode 100644 shared/data/trafficTiers.ts
 create mode 100644 shared/utils/aiTraffic/callsign.ts
 create mode 100644 shared/utils/aiTraffic/gating.ts
 create mode 100644 shared/utils/aiTraffic/instructions.ts
 create mode 100644 shared/utils/aiTraffic/rng.ts
 create mode 100644 shared/utils/aiTraffic/separation.ts
 create mode 100644 shared/utils/aiTraffic/sim.ts
 create mode 100644 shared/utils/aiTraffic/types.ts
 create mode 100644 shared/utils/voicePool.ts
 create mode 100644 tests/shared/aiTrafficCallsign.test.ts
 create mode 100644 tests/shared/aiTrafficGating.test.ts
 create mode 100644 tests/shared/aiTrafficInstructions.test.ts
 create mode 100644 tests/shared/aiTrafficIntegration.test.ts
 create mode 100644 tests/shared/aiTrafficSeparation.test.ts
 create mode 100644 tests/shared/aiTrafficSim.test.ts
 create mode 100644 tests/shared/trafficTiers.test.ts
 create mode 100644 tests/shared/voicePool.test.ts

diff --git a/app/components/live-atc/cockpit/SettingsSheet.vue b/app/components/live-atc/cockpit/SettingsSheet.vue
index 8260d42..973051a 100644
--- a/app/components/live-atc/cockpit/SettingsSheet.vue
+++ b/app/components/live-atc/cockpit/SettingsSheet.vue
@@ -19,6 +19,20 @@ const learningMode = defineModel<boolean>('learningMode', { required: true })
 const debugMode = defineModel<boolean>('debugMode', { required: true })
 const prerecEnabled = defineModel<boolean>('prerecEnabled', { required: true })
 const prerecSeconds = defineModel<number>('prerecSeconds', { required: true })
+const aiTrafficEnabled = defineModel<boolean>('aiTrafficEnabled', { required: true })
+
+/**
+ * Shown while AI traffic is on. These are deliberate v1 boundaries from the
+ * architecture design, not bugs — stating them up front is cheaper than having
+ * someone discover them mid-session and file them as defects.
+ */
+const AI_TRAFFIC_LIMITS = [
+  'Background scenery only — it never affects how your own radio work is scored.',
+  'Audible on the tuned frequency only. Other frequencies stay busy, just silent.',
+  'Never transmits while you hold PTT, while ATC is answering you, or in the ~12s after an instruction.',
+  'Fixed phraseology, no AI text generation. Invented waypoint names, not real SIDs/STARs.',
+  'Traffic never conflicts with you: it always yields, and you get no extra instructions from it.',
+]
 </script>
 
 <template>
@@ -116,6 +130,34 @@ const prerecSeconds = defineModel<number>('prerecSeconds', { required: true })
           />
         </div>
 
+        <div class="pt-2 border-t border-white/10 space-y-3">
+          <div>
+            <p class="text-xs uppercase tracking-[0.3em] text-white/40">Frequency</p>
+            <p class="text-[11px] text-white/50 mt-1">
+              Simulated other aircraft on your frequency — callsigns, readbacks, handovers — so the
+              band sounds alive while you fly.
+            </p>
+          </div>
+          <v-switch
+              v-model="aiTrafficEnabled"
+              color="cyan"
+              inset
+              label="AI traffic (background chatter)"
+              hide-details
+          />
+          <!-- Surfaced rather than buried in a doc: every one of these is a
+               deliberate v1 boundary, and knowing them up front is what stops
+               them from reading as broken behaviour. -->
+          <v-expand-transition>
+            <ul v-if="aiTrafficEnabled" class="pm-ai-limits">
+              <li v-for="limit in AI_TRAFFIC_LIMITS" :key="limit">
+                <v-icon size="13" class="pm-ai-limits__icon">mdi-information-outline</v-icon>
+                <span>{{ limit }}</span>
+              </li>
+            </ul>
+          </v-expand-transition>
+        </div>
+
         <div class="pt-2 border-t border-white/10 space-y-3">
           <div>
             <p class="text-xs uppercase tracking-[0.3em] text-white/40">Voice input</p>
@@ -155,6 +197,33 @@ const prerecSeconds = defineModel<number>('prerecSeconds', { required: true })
 </template>
 
 <style scoped>
+/* The AI-traffic caveats. Quiet by design — they inform, they don't warn. */
+.pm-ai-limits {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: 12px;
+  border: 1px solid color-mix(in srgb, #22d3ee 22%, transparent);
+  background: color-mix(in srgb, #22d3ee 7%, transparent);
+  list-style: none;
+}
+.pm-ai-limits li {
+  display: flex;
+  align-items: flex-start;
+  gap: 7px;
+  font-size: 11px;
+  line-height: 1.45;
+  color: var(--t3);
+}
+.pm-ai-limits__icon {
+  flex: none;
+  margin-top: 1px;
+  color: #22d3ee;
+  opacity: 0.75;
+}
+
 /* Mirrors the page's segmented control so the sheet doesn't depend on
    live-atc.vue's scoped styles reaching a teleported dialog. */
 .pm-seg {
diff --git a/app/composables/useAiTraffic.ts b/app/composables/useAiTraffic.ts
new file mode 100644
index 0000000..d8de586
--- /dev/null
+++ b/app/composables/useAiTraffic.ts
@@ -0,0 +1,456 @@
+import { computed, onUnmounted, ref, type Ref } from 'vue'
+import { pmLog } from '../../shared/utils/pmLog'
+import useCommunicationsEngine from '../../shared/utils/communicationsEngine'
+import type { useFrequencyPresets } from '~/composables/useFrequencyPresets'
+import type { useRadioSpeech } from '~/composables/useRadioSpeech'
+import { FREQ_ROLE_LABEL, normalizedFrequencyValue } from '~/composables/useFrequencyPresets'
+import { MAX_ACTIVE_TRAFFIC, resolveTrafficTier, targetTrafficCount } from '../../shared/data/trafficTiers'
+import { createRng, trafficSeed, type Rng } from '../../shared/utils/aiTraffic/rng'
+import { createCallsignFactory } from '../../shared/utils/aiTraffic/callsign'
+import {
+  DEFAULT_READBACK_PROTECTION_MS,
+  evaluateGate,
+  type GateInput,
+} from '../../shared/utils/aiTraffic/gating'
+import {
+  applyDirect,
+  cooldownSecFor,
+  planInstruction,
+  renderInstruction,
+  type RadioEvent,
+} from '../../shared/utils/aiTraffic/instructions'
+import { nextFreeSlot } from '../../shared/utils/aiTraffic/separation'
+import {
+  NM_PER_FIX,
+  advanceAircraft,
+  advancePhase,
+  createSimAircraft,
+  findLeader,
+  generateFixPool,
+  isArrival,
+  isDespawnable,
+} from '../../shared/utils/aiTraffic/sim'
+import type { SimAircraft } from '../../shared/utils/aiTraffic/types'
+
+/**
+ * Simulated background traffic on the tuned frequency (`ai-traffic`).
+ *
+ * A pure OBSERVER: it reads the engine, the session and the PTT state, and it
+ * writes only to the speech queue and the communication log. It never touches
+ * radioBackend — the Python backend owns the dialogue *with* the user, this owns
+ * the radio *around* the user. The two share exactly two things: the speech
+ * queue (arbitration) and the log (display).
+ *
+ * See docs/plans/2026-07-14-ai-traffic-architecture-design.md — this composable
+ * is the design's four internal modules (CallsignFactory, TrafficSim,
+ * InstructionPlanner, RadioScheduler) wired to Vue; all the rules themselves live
+ * as pure functions under shared/utils/aiTraffic/ so they test without a browser.
+ */
+
+const TICK_MS = 1000
+
+/** Traffic pairs are short by design, so a real ATC reply never waits long. */
+const READBACK_DELAY_MS = 700
+const ATC_REPLY_DELAY_MS = 900
+
+/** Spawner cadence — a new arrival/departure every 30–120 s while under target. */
+const SPAWN_INTERVAL_MIN_SEC = 30
+const SPAWN_INTERVAL_MAX_SEC = 120
+
+/** Runway occupancy booked per movement. */
+const RUNWAY_SLOT_SEC = 90
+
+export interface AiTrafficDeps {
+  /** The settings toggle. */
+  aiTrafficEnabled: Ref<boolean>
+  /** usePttRecording — the user is holding PTT. */
+  isRecording: Ref<boolean>
+  /** useLiveAtcSession — a user transmission is out at the backend. */
+  transmitInFlight: Ref<boolean>
+  backendSessionId: Ref<string | null>
+  backendExpectedPhrase: Ref<string | null>
+  /** Stamped by scheduleControllerSpeech — opens the readback window. */
+  lastControllerSpeechAtMs: Ref<number | null>
+  currentScreen: Ref<'login' | 'flightselect' | 'scenario' | 'monitor' | 'complete'>
+  freq: ReturnType<typeof useFrequencyPresets>
+  speech: ReturnType<typeof useRadioSpeech>
+  /** Infinity for the literal-strict reading of "ATC is awaiting a readback". */
+  readbackProtectionMs?: number
+}
+
+export function useAiTraffic(
+  engine: ReturnType<typeof useCommunicationsEngine>,
+  deps: AiTrafficDeps,
+) {
+  const { currentState, variables: vars, appendLogEntry } = engine
+  const {
+    aiTrafficEnabled, isRecording, transmitInFlight,
+    backendSessionId, backendExpectedPhrase, lastControllerSpeechAtMs,
+    currentScreen, freq, speech,
+  } = deps
+  const { frequencies, airportFrequencies, airportName, activeAirportIcao } = freq
+  const { speakWithRadioEffects } = speech
+
+  // --- Pool state --------------------------------------------------------------
+  let rng: Rng | null = null
+  let callsigns: ReturnType<typeof createCallsignFactory> | null = null
+  let fixPool: string[] = []
+  let timer: ReturnType<typeof setInterval> | null = null
+
+  /** Sim clock in seconds since start() — the timeline everything is booked on. */
+  let nowSec = 0
+  let nextSpawnAtSec = 0
+  /** When the tuned frequency last carried anything, for ambient chatter. */
+  let lastRadioAtSec = 0
+  let ambientAfterSec = 60
+  /** The last departure to use the runway, for the wake timer. */
+  let lastDeparture: { type: SimAircraft['type']; atSec: number } | null = null
+
+  const pool = ref<SimAircraft[]>([])
+  /** Events whose gate was shut — re-checked on the next tick, never dropped. */
+  const pending = ref<RadioEvent[]>([])
+  const running = ref(false)
+
+  /** Only what is on the tuned frequency is audible; the rest lives on, silently. */
+  const audible = computed(() =>
+    pool.value.filter(ac => normalizedFrequencyValue(ac.frequency) === normalizedFrequencyValue(frequencies.value.active)),
+  )
+
+  // --- Gating ------------------------------------------------------------------
+
+  const gateInput = (): GateInput => ({
+    aiTrafficEnabled: aiTrafficEnabled.value,
+    isRecording: isRecording.value,
+    transmitInFlight: transmitInFlight.value,
+    sessionActive: Boolean(backendSessionId.value) && currentScreen.value === 'monitor',
+    readback: {
+      currentStateRole: (currentState.value as any)?.role,
+      backendExpectedPhrase: backendExpectedPhrase.value,
+      lastControllerSpeechAtMs: lastControllerSpeechAtMs.value,
+      nowMs: Date.now(),
+      readbackProtectionMs: deps.readbackProtectionMs ?? DEFAULT_READBACK_PROTECTION_MS,
+    },
+  })
+
+  /** The chain, evaluated fresh. Called before enqueue AND again at playback. */
+  const gateOpen = () => evaluateGate(gateInput()).open
+
+  // --- Station / runway context ------------------------------------------------
+
+  /** e.g. 'Frankfurt Approach' — whoever owns the frequency the traffic is on. */
+  const stationName = () => {
+    const active = normalizedFrequencyValue(frequencies.value.active)
+    const entry = airportFrequencies.value.find(e => normalizedFrequencyValue(e.frequency) === active)
+    const role = entry ? (FREQ_ROLE_LABEL[entry.type] || entry.type) : 'Radar'
+    return airportName.value ? `${airportName.value} ${role}` : role
+  }
+
+  const activeRunway = () => String((vars as any).value?.runway || '25R')
+
+  /**
+   * Every reservation on the runway, the user's included. The user's aircraft is
+   * a slot reservation, never a simulated position — simulated traffic always
+   * yields to it, so the user never gets an extra instruction or delay out of
+   * background traffic. Their flow belongs to the backend alone.
+   */
+  const occupiedSlots = () => {
+    const slots = pool.value.filter(ac => ac.runwaySlot).map(ac => ac.runwaySlot!)
+    const userSlot = userRunwayReservation()
+    return userSlot ? [...slots, userSlot] : slots
+  }
+
+  /**
+   * Derive the user's runway occupancy from the flow state. Departure flows block
+   * the runway from line-up until airborne; arrival flows from the landing
+   * clearance until the runway is vacated.
+   */
+  const userRunwayReservation = () => {
+    const stateId = String((currentState.value as any)?.id || '').toLowerCase()
+    if (!stateId) return null
+    const blocking = /(line_?up|lineup|takeoff|take_?off|departure_roll|land|final|rollout|vacate)/.test(stateId)
+    if (!blocking) return null
+    // The user owns the runway for as long as they are on such a state; the slot
+    // simply keeps being re-derived each tick while that holds.
+    return { fromSec: nowSec, toSec: nowSec + RUNWAY_SLOT_SEC }
+  }
+
+  // --- Spawner -----------------------------------------------------------------
+
+  const trafficTier = () =>
+    resolveTrafficTier(activeAirportIcao.value, airportFrequencies.value.map(e => e.type))
+
+  const targetPopulation = () => targetTrafficCount(trafficTier(), new Date().getHours())
+
+  const spawnOne = () => {
+    if (!rng || !callsigns) return
+    if (pool.value.length >= MAX_ACTIVE_TRAFFIC) return
+    const generated = callsigns.next()
+    if (!generated) return // no distinct callsign available — simply don't spawn
+
+    const kind = rng.chance(0.6) ? 'arrival' : 'departure'
+    const aircraft = createSimAircraft(generated, kind, {
+      rng,
+      nowSec,
+      frequency: frequencies.value.active,
+      fixPool,
+    })
+    // Book the runway as late as it is free — traffic never cuts into a slot.
+    const desired = { fromSec: nowSec + 120, toSec: nowSec + 120 + RUNWAY_SLOT_SEC }
+    aircraft.runwaySlot = nextFreeSlot(desired, occupiedSlots())
+    pool.value.push(aircraft)
+    pmLog.debug('AI-TRAFFIC spawn', aircraft.callsign, aircraft.type.icao, kind)
+  }
+
+  const despawn = (aircraft: SimAircraft) => {
+    callsigns?.release(aircraft.callsign)
+    pool.value = pool.value.filter(ac => ac !== aircraft)
+    pending.value = pending.value.filter(e => e.callsign !== aircraft.callsign)
+    pmLog.debug('AI-TRAFFIC despawn', aircraft.callsign)
+  }
+
+  // --- RadioScheduler ----------------------------------------------------------
+
+  /**
+   * Speak one event as an atomic ATC-call + readback pair, so a real ATC reply
+   * can never slot itself between the two. Only the FIRST element carries the
+   * gate: once an exchange has started it plays out, exactly as a real frequency
+   * would. The gate on that first element is the playback-time re-check — the
+   * enqueue-time check already happened in dispatch().
+   */
+  const speakPair = (event: RadioEvent, aircraft: SimAircraft) => {
+    const controllerFirst = event.order === 'atc_first'
+    const first = controllerFirst
+      ? { text: event.atcText, voice: undefined, speaker: 'atc' as const, delay: ATC_REPLY_DELAY_MS }
+      : { text: event.pilotReadbackText, voice: aircraft.voiceId, speaker: 'pilot' as const, delay: 0 }
+    const second = controllerFirst
+      ? { text: event.pilotReadbackText, voice: aircraft.voiceId, speaker: 'pilot' as const, delay: READBACK_DELAY_MS }
+      : { text: event.atcText, voice: undefined, speaker: 'atc' as const, delay: ATC_REPLY_DELAY_MS }
+
+    const log = (speaker: 'atc' | 'pilot', text: string) =>
+      appendLogEntry(speaker, text, currentState.value?.id ?? '', {
+        frequency: aircraft.frequency,
+        traffic: true,
+      })
+
+    // Only true once the first half has actually committed to being spoken. The
+    // model update and the log hang off that, not off enqueueing: if the gate
+    // shuts at playback the event goes back on the queue, and applying its
+    // effects here would then apply them twice — splicing a direct out of the
+    // route twice, or silently skipping a phase.
+    let firstSpoken = false
+
+    speakWithRadioEffects(first.text, {
+      voice: first.voice,
+      tag: 'ai-traffic',
+      delayMs: first.delay,
+      updateLastTransmission: false,
+      useNormalizedForTTS: true,
+      gate: gateOpen,
+      onGateClosed: () => {
+        pending.value.push(event)
+        pmLog.debug('AI-TRAFFIC gate closed at playback —', event.callsign, 'requeued')
+      },
+      onSpoken: () => {
+        firstSpoken = true
+        lastRadioAtSec = nowSec
+        log(first.speaker, first.text)
+        applyEventEffects(event, aircraft)
+      },
+    })
+    speakWithRadioEffects(second.text, {
+      voice: second.voice,
+      tag: 'ai-traffic',
+      delayMs: second.delay,
+      updateLastTransmission: false,
+      useNormalizedForTTS: true,
+      // Bound to the first half, not to the gating chain: once an exchange has
+      // started it plays out (a real frequency doesn't cut off mid-readback), but
+      // a pair that never started must not answer itself.
+      gate: () => firstSpoken,
+      onSpoken: () => log(second.speaker, second.text),
+    })
+  }
+
+  /** The model update an instruction implies, applied once it has been spoken. */
+  const applyEventEffects = (event: RadioEvent, aircraft: SimAircraft) => {
+    const plan = event.plan
+    // Leave this aircraft alone until the instruction has had time to work.
+    aircraft.quietUntilSec = nowSec + cooldownSecFor(plan)
+    switch (plan.kind) {
+      case 'speed':
+        if (aircraft.type.wake !== 'L' && plan.speedKts) aircraft.assignedSpeedKts = plan.speedKts
+        break
+      case 'vector':
+        aircraft.vectorDelaySec += plan.vectorDelaySec ?? 90
+        break
+      case 'direct':
+        if (plan.direct) applyDirect(aircraft, plan.direct)
+        break
+      case 'wake_hold':
+        aircraft.nextEventAtSec = nowSec + (plan.holdSec ?? 60)
+        if (aircraft.runwaySlot) {
+          aircraft.runwaySlot = nextFreeSlot(
+            { fromSec: nowSec + (plan.holdSec ?? 60), toSec: nowSec + (plan.holdSec ?? 60) + RUNWAY_SLOT_SEC },
+            occupiedSlots().filter(s => s !== aircraft.runwaySlot),
+          )
+        }
+        break
+      case 'slot_hold':
+        if (aircraft.runwaySlot) {
+          aircraft.runwaySlot = nextFreeSlot(
+            aircraft.runwaySlot,
+            occupiedSlots().filter(s => s !== aircraft.runwaySlot),
+          )
+          aircraft.nextEventAtSec = aircraft.runwaySlot.fromSec
+        }
+        break
+      case 'handover':
+        aircraft.phase = 'handed_off'
+        break
+      case 'phase':
+        if (rng) {
+          advancePhase(aircraft, rng, nowSec)
+          if (aircraft.phase === 'takeoff') lastDeparture = { type: aircraft.type, atSec: nowSec }
+        }
+        break
+      default:
+        break
+    }
+  }
+
+  /** Try to get one pending event onto the frequency. One pair per tick, at most. */
+  const dispatch = () => {
+    if (!pending.value.length) return
+    // Enqueue-time check. The same chain runs again at playback (see speakPair).
+    const gate = evaluateGate(gateInput())
+    if (!gate.open) return
+
+    const event = pending.value.shift()!
+    const aircraft = pool.value.find(ac => ac.callsign === event.callsign)
+    if (!aircraft) return // despawned while the event sat in the queue
+    speakPair(event, aircraft)
+  }
+
+  // --- The 1 Hz tick -----------------------------------------------------------
+
+  const tick = () => {
+    if (!running.value || !rng) return
+    nowSec += TICK_MS / 1000
+
+    for (const aircraft of [...pool.value]) {
+      advanceAircraft(aircraft, TICK_MS / 1000)
+      if (isDespawnable(aircraft)) despawn(aircraft)
+    }
+
+    // Population control. `target` can legitimately be 0 (a GA field at 03:00).
+    const target = targetPopulation()
+    if (pool.value.length > target) {
+      // Over target (the clock crossed a band): let the extras leave quietly
+      // rather than teleporting them away mid-exchange.
+      const surplus = pool.value.filter(ac => !pending.value.some(e => e.callsign === ac.callsign))
+      surplus.slice(target).forEach(ac => despawn(ac))
+    } else if (pool.value.length < target && nowSec >= nextSpawnAtSec) {
+      spawnOne()
+      nextSpawnAtSec = nowSec + rng.int(SPAWN_INTERVAL_MIN_SEC, SPAWN_INTERVAL_MAX_SEC)
+    }
+
+    // Plan at most one new event per tick — the queue is FIFO and short pairs are
+    // the whole point; flooding it would delay a real ATC reply.
+    if (pending.value.length === 0) {
+      for (const aircraft of audible.value) {
+        const plan = planInstruction(aircraft, {
+          nowSec,
+          rng,
+          leader: findLeader(aircraft, audible.value.filter(isArrival)),
+          occupiedSlots: occupiedSlots(),
+          lastDeparture,
+          handover: aircraft.phase === 'handed_off' ? null : handoverFor(aircraft),
+          nmPerFix: NM_PER_FIX,
+          silentForSec: nowSec - lastRadioAtSec,
+          ambientAfterSec,
+        })
+        if (!plan) continue
+        pending.value.push(renderInstruction(aircraft, plan, {
+          rng,
+          station: stationName(),
+          runway: activeRunway(),
+        }))
+        // Re-roll the ambient threshold so the frequency doesn't fall into a rhythm.
+        ambientAfterSec = rng.int(45, 90)
+        break
+      }
+    }
+
+    dispatch()
+  }
+
+  /** Where an aircraft goes once it leaves this sector — the last call it makes. */
+  const handoverFor = (aircraft: SimAircraft) => {
+    const leaving =
+      (aircraft.phase === 'climbout' && aircraft.altitudeFt > 6000)
+      || (aircraft.phase === 'rollout' && aircraft.iasKts <= 0)
+    if (!leaving) return null
+    const entry = airportFrequencies.value.find(e => (aircraft.phase === 'climbout' ? e.type === 'DEP' || e.type === 'CTR' : e.type === 'GND'))
+    if (!entry?.frequency) return null
+    return {
+      station: airportName.value ? `${airportName.value} ${FREQ_ROLE_LABEL[entry.type] || entry.type}` : (FREQ_ROLE_LABEL[entry.type] || entry.type),
+      frequency: entry.frequency,
+    }
+  }
+
+  // --- Lifecycle ---------------------------------------------------------------
+
+  /** Called once startMonitoring() has a live backend session. */
+  const start = (sessionId: string, airportIcao?: string) => {
+    stop()
+    const seed = trafficSeed(sessionId)
+    rng = createRng(seed)
+    fixPool = generateFixPool(createRng(`${seed}|${airportIcao ?? 'fixes'}`))
+    callsigns = createCallsignFactory({
+      rng,
+      tier: trafficTier(),
+      userCallsigns: [
+        (vars as any).value?.callsign,
+        (vars as any).value?.callsign_short,
+      ].filter(Boolean),
+    })
+    nowSec = 0
+    lastRadioAtSec = 0
+    nextSpawnAtSec = 0
+    lastDeparture = null
+    ambientAfterSec = rng.int(45, 90)
+    pool.value = []
+    pending.value = []
+    running.value = true
+    timer = setInterval(tick, TICK_MS)
+    pmLog.info('AI-TRAFFIC start', { seed, tier: trafficTier(), target: targetPopulation() })
+  }
+
+  /**
+   * Spawner off, pool empty, pending events dropped. Anything already enqueued
+   * invalidates itself through the playback-time gate, and the call that is
+   * physically playing right now finishes (≤ ~8 s) — stopCurrentSpeech() is
+   * global and would take a real queued ATC reply down with it.
+   */
+  const stop = () => {
+    if (timer) { clearInterval(timer); timer = null }
+    running.value = false
+    pool.value = []
+    pending.value = []
+    rng = null
+    callsigns = null
+    lastDeparture = null
+  }
+
+  onUnmounted(stop)
+
+  return {
+    start,
+    stop,
+    running,
+    /** Exposed for the debug panel: who is currently on the tuned frequency. */
+    audible,
+    pool,
+    gateState: () => evaluateGate(gateInput()),
+  }
+}
diff --git a/app/composables/useLiveAtcSession.ts b/app/composables/useLiveAtcSession.ts
index 9174ae6..2c90420 100644
--- a/app/composables/useLiveAtcSession.ts
+++ b/app/composables/useLiveAtcSession.ts
@@ -1,4 +1,4 @@
-import { nextTick, onUnmounted } from 'vue'
+import { computed, nextTick, onUnmounted, ref } from 'vue'
 import type { Ref } from 'vue'
 import { pmLog } from '../../shared/utils/pmLog'
 import { SCENARIOS, type Scenario } from '../../shared/constants/scenarios'
@@ -87,6 +87,14 @@ export function useLiveAtcSession(
   // awaiting its backend response — only the latest result is applied (#16).
   let transmitGeneration = 0
 
+  // True while a pilot transmission is out at the backend. Read by useAiTraffic's
+  // gating chain: simulated traffic must not key up in the window between the
+  // user finishing their call and ATC answering it, or the traffic call reads as
+  // the reply. A counter rather than a boolean, so two overlapping transmissions
+  // can't have the first one's finally clear the flag out from under the second.
+  const transmitInFlightCount = ref(0)
+  const transmitInFlight = computed(() => transmitInFlightCount.value > 0)
+
   // --- Silence auto-advance ----------------------------------------------------
   // Some pilot states let ATC continue on its own when the pilot stays quiet
   // (e.g. the takeoff roll in tower-v1: no report needed, Tower hands off after a
@@ -378,6 +386,7 @@ export function useLiveAtcSession(
       pmLog.info('session_id  :', backendSessionId.value)
     })
 
+    transmitInFlightCount.value++
     try {
       // The pilot spoke — a pending silence auto-advance no longer applies. The
       // response re-arms it if the next state also allows silence.
@@ -421,6 +430,8 @@ export function useLiveAtcSession(
       pmLog.error('TRANSMIT FAILED', { transcript, session: backendSessionId.value, error: e })
       console.error('Backend transmission failed', e)
       setLastTransmission(`${prefix}: ${transcript} (backend failed)`)
+    } finally {
+      transmitInFlightCount.value = Math.max(0, transmitInFlightCount.value - 1)
     }
   }
 
@@ -755,6 +766,7 @@ export function useLiveAtcSession(
 
   return {
     clearSilenceTimer,
+    transmitInFlight,
     applyBackendDecision,
     handlePilotTransmission,
     handleSimControlResult,
diff --git a/app/composables/useRadioSpeech.ts b/app/composables/useRadioSpeech.ts
index bdbc8ce..8e2dab9 100644
--- a/app/composables/useRadioSpeech.ts
+++ b/app/composables/useRadioSpeech.ts
@@ -28,12 +28,33 @@ export type SpeechOptions = {
   useNormalizedForTTS?: boolean
   speed?: number
   lessonId?: string
+  /**
+   * Re-checked inside the queued task, immediately before playback. Enqueue time
+   * and play time can be seconds apart, so a caller whose right to the frequency
+   * can lapse in between (today: useAiTraffic's gating chain) passes this and the
+   * task drops itself instead of talking over whoever now owns it.
+   */
+  gate?: () => boolean
+  /** Called when `gate` returned false — the caller can re-queue its event. */
+  onGateClosed?: () => void
+  /**
+   * Called once the task has committed to this transmission and run it. The
+   * counterpart to `onGateClosed`: exactly one of the two fires, so a caller can
+   * apply state changes only for what was actually said.
+   */
+  onSpoken?: () => void
 }
 
 export interface RadioSpeechDeps {
   setLastTransmission: (text: string) => void
   handlePilotTransmission: (message: string, source: 'text' | 'ptt') => Promise<void>
   lastControllerSay: Ref<string | null>
+  /**
+   * Stamped by scheduleControllerSpeech — opens the readback window that keeps
+   * simulated traffic silent (useAiTraffic). Only the user-facing ATC reply goes
+   * through that function, so traffic never opens a window against itself.
+   */
+  lastControllerSpeechAtMs: Ref<number | null>
   signalStrength: Ref<number>
   speechSpeed: Ref<number>
   radioCheckLoading: Ref<boolean>
@@ -56,7 +77,7 @@ export function useRadioSpeech(
     setCurrentAudio, setCurrentPizzicatoSound, addPendingAbort, deletePendingAbort,
   } = speechInterrupt
   const {
-    setLastTransmission, handlePilotTransmission, lastControllerSay,
+    setLastTransmission, handlePilotTransmission, lastControllerSay, lastControllerSpeechAtMs,
     signalStrength, speechSpeed, radioCheckLoading, radioEffectsEnabled, readbackEnabled,
   } = deps
   const api = useApi()
@@ -263,6 +284,11 @@ export function useRadioSpeech(
         await wait(delay)
       }
       if (generation !== getSpeechGeneration()) return // stopped while waiting
+      if (options.gate && !options.gate()) {
+        options.onGateClosed?.()
+        return // the frequency stopped being ours while we sat in the queue
+      }
+      options.onSpoken?.()
       await speakPrepared(prepared, options, audioPromise)
     })
   }
@@ -303,6 +329,9 @@ export function useRadioSpeech(
 
   const scheduleControllerSpeech = (tpl: string) => {
     const plain = renderATCMessage(tpl)
+    // Opens the readback window: from here until the pilot answers (and for at
+    // least readbackProtectionMs), background traffic stays off the frequency.
+    lastControllerSpeechAtMs.value = Date.now()
     speakWithRadioEffects(tpl, {
       delayMs: 800 + Math.random() * 2000,
       tag: 'controller-reply',
diff --git a/app/composables/useSessionState.ts b/app/composables/useSessionState.ts
index 37680c5..bf685c3 100644
--- a/app/composables/useSessionState.ts
+++ b/app/composables/useSessionState.ts
@@ -51,6 +51,9 @@ export function useSessionState(engine: ReturnType<typeof useCommunicationsEngin
   const backendSessionId = ref<string | null>(null)
   // Last ATC utterance returned by the backend (pre-rendered, correct variables).
   const lastControllerSay = ref<string | null>(null)
+  // When that utterance was scheduled — opens the readback window during which
+  // simulated background traffic must stay silent (useAiTraffic's gating chain).
+  const lastControllerSpeechAtMs = ref<number | null>(null)
   // Authoritative expected pilot phrase from the backend — replaces local engine rendering.
   const backendExpectedPhrase = ref<string | null>(null)
   // Per-field readback diagnostic from the last transmission (STT debug panel).
@@ -160,6 +163,7 @@ export function useSessionState(engine: ReturnType<typeof useCommunicationsEngin
     sessionStartingMessage,
     backendSessionId,
     lastControllerSay,
+    lastControllerSpeechAtMs,
     backendExpectedPhrase,
     lastReadbackReport,
     lastReadbackTranscript,
diff --git a/app/pages/live-atc.vue b/app/pages/live-atc.vue
index ef8e4a3..bb89f39 100644
--- a/app/pages/live-atc.vue
+++ b/app/pages/live-atc.vue
@@ -139,6 +139,7 @@
             v-model:debug-mode="debugMode"
             v-model:prerec-enabled="prerecEnabled"
             v-model:prerec-seconds="prerecSeconds"
+            v-model:ai-traffic-enabled="aiTrafficEnabled"
             @set-theme="setPmTheme"
         />
 
@@ -192,6 +193,7 @@ import FlightSourceStep from '~/components/live-atc/FlightSourceStep.vue'
 import FlightSelectStep from '~/components/live-atc/FlightSelectStep.vue'
 import ScenarioPickerStep from '~/components/live-atc/ScenarioPickerStep.vue'
 import SessionCompleteStep from '~/components/live-atc/SessionCompleteStep.vue'
+import { useAiTraffic } from '~/composables/useAiTraffic'
 import { useLiveAtcSession } from '~/composables/useLiveAtcSession'
 import { useSessionState } from '~/composables/useSessionState'
 import { useSpeechInterrupt } from '~/composables/useSpeechInterrupt'
@@ -212,6 +214,7 @@ const STORAGE_KEYS = {
   vatsimId: 'pm_vatsim_id',
   prerecEnabled: 'pm_prerec_enabled',
   prerecSeconds: 'pm_prerec_seconds',
+  aiTrafficEnabled: 'pm_ai_traffic_enabled',
   helpSeen: 'pm_help_seen',
   helpLang: 'pm_help_lang',
 } as const
@@ -281,6 +284,7 @@ const {
   sessionStartingMessage,
   backendSessionId,
   lastControllerSay,
+  lastControllerSpeechAtMs,
   backendExpectedPhrase,
   lastReadbackReport,
   lastReadbackTranscript,
@@ -308,6 +312,9 @@ const speechSpeed = ref(0.95)
 const radioCheckLoading = ref(false)
 const radioEffectsEnabled = ref(true)
 const readbackEnabled = ref(false)
+// Simulated background traffic. Off by default: it costs TTS per lively minute,
+// so it stays an opt-in the user turns on once they want the busier frequency.
+const aiTrafficEnabled = ref(false)
 
 // ── Bug Report ───────────────────────────────────────────────────────────────
 // Owned here rather than by the dialog: the HUD button starts the screenshot
@@ -370,6 +377,11 @@ onMounted(async () => {
       if (storedPrerecEnabled !== null) {
         prerecEnabled.value = storedPrerecEnabled === '1'
       }
+      const storedAiTraffic = window.localStorage.getItem(STORAGE_KEYS.aiTrafficEnabled)
+      if (storedAiTraffic !== null) {
+        aiTrafficEnabled.value = storedAiTraffic === '1'
+      }
+
       const storedPrerecSeconds = window.localStorage.getItem(STORAGE_KEYS.prerecSeconds)
       if (storedPrerecSeconds !== null) {
         const parsed = Number.parseFloat(storedPrerecSeconds)
@@ -433,6 +445,7 @@ const freq = useFrequencyPresets(engine, stopCurrentSpeech)
 const {
   frequencies,
   airportName,
+  activeAirportIcao,
   displayAirportFrequencies,
   swapAnimation,
   manualFreqActive,
@@ -470,6 +483,7 @@ const speech = useRadioSpeech(engine, freq, speechInterrupt, {
   setLastTransmission,
   handlePilotTransmission,
   lastControllerSay,
+  lastControllerSpeechAtMs,
   signalStrength,
   speechSpeed,
   radioCheckLoading,
@@ -541,6 +555,12 @@ watch(prerecEnabled, (val) => {
   }
 })
 
+watch(aiTrafficEnabled, (val) => {
+  if (typeof window !== 'undefined') {
+    window.localStorage.setItem(STORAGE_KEYS.aiTrafficEnabled, val ? '1' : '0')
+  }
+})
+
 const {
   bridgeToken,
   bridgeConnected,
@@ -574,6 +594,7 @@ const session = useLiveAtcSession(engine, {
   maybeShowFirstRunHelp,
 })
 const {
+  transmitInFlight,
   loadFlightPlans,
   startMonitoring,
   startDemoFlight,
@@ -584,10 +605,43 @@ const {
   restoreBugReportState,
 } = session
 
+// Simulated background traffic. A pure observer alongside the engine and the
+// session — it reads state and writes only to the speech queue and the log, and
+// never touches radioBackend. Constructed after `session` because it needs that
+// composable's transmitInFlight for its gating chain.
+const aiTraffic = useAiTraffic(engine, {
+  aiTrafficEnabled,
+  isRecording,
+  transmitInFlight,
+  backendSessionId,
+  backendExpectedPhrase,
+  lastControllerSpeechAtMs,
+  currentScreen,
+  freq,
+  speech,
+})
+
+// The single owner of the traffic lifecycle: it runs exactly while the toggle is
+// on, a backend session exists and we're on the monitor screen. Every entry and
+// exit the design lists — startMonitoring() succeeding, session_complete,
+// backToSetup, toggling mid-session — moves one of these three, so they need no
+// separate hooks. Toggling back on rebuilds from a fresh spawn-up.
+watch(
+  [backendSessionId, currentScreen, aiTrafficEnabled],
+  ([sessionId, screen, enabled]) => {
+    if (enabled && sessionId && screen === 'monitor') {
+      aiTraffic.start(sessionId, activeAirportIcao.value)
+    } else {
+      aiTraffic.stop()
+    }
+  },
+)
+
 onUnmounted(() => {
   stopAtisLoop()
   stopPrerecCapture()
   cancelAirportDataRefresh()
+  aiTraffic.stop()
 })
 </script>
 
diff --git a/shared/data/simAircraftTypes.ts b/shared/data/simAircraftTypes.ts
new file mode 100644
index 0000000..74cd798
--- /dev/null
+++ b/shared/data/simAircraftTypes.ts
@@ -0,0 +1,57 @@
+/**
+ * Reference aircraft performance database for the simulated background traffic
+ * (`ai-traffic`). Deliberately small and extendable — it only carries the fields
+ * the instruction planner needs to stay plausible: wake category (separation
+ * matrix), the speeds a controller may legally assign, and whether the callsign
+ * gets a "heavy"/"super" suffix.
+ *
+ * Values are the common ATC-training approximations from the architecture design
+ * (docs/plans/2026-07-14-ai-traffic-architecture-design.md § 2), not a certified
+ * ICAO Doc 4444 citation.
+ */
+
+/** Wake turbulence category: Light, Medium, Heavy, Super. */
+export type WakeCategory = 'L' | 'M' | 'H' | 'J'
+
+/** Rough size class — drives the type mix per traffic tier. */
+export type SimAircraftClass = 'ga' | 'regional' | 'narrowbody' | 'widebody'
+
+export interface SimAircraftType {
+  icao: string
+  class: SimAircraftClass
+  wake: WakeCategory
+  cruiseKts: number
+  climbFpm: number
+  descentFpm: number
+  /** Vref / final approach speed — the hard floor for any speed instruction. */
+  approachKts: number
+  /** Spoken callsign suffix, if the type carries one. */
+  heavyCallsign: false | 'heavy' | 'super'
+}
+
+export const SIM_AIRCRAFT_TYPES: readonly SimAircraftType[] = [
+  { icao: 'C172', class: 'ga',         wake: 'L', cruiseKts: 110, climbFpm: 700,  descentFpm: 500,  approachKts: 60,  heavyCallsign: false },
+  { icao: 'PA28', class: 'ga',         wake: 'L', cruiseKts: 120, climbFpm: 750,  descentFpm: 500,  approachKts: 65,  heavyCallsign: false },
+  { icao: 'DA40', class: 'ga',         wake: 'L', cruiseKts: 135, climbFpm: 800,  descentFpm: 600,  approachKts: 70,  heavyCallsign: false },
+  { icao: 'E190', class: 'regional',   wake: 'M', cruiseKts: 450, climbFpm: 2200, descentFpm: 1800, approachKts: 135, heavyCallsign: false },
+  { icao: 'CRJ9', class: 'regional',   wake: 'M', cruiseKts: 450, climbFpm: 2000, descentFpm: 1800, approachKts: 130, heavyCallsign: false },
+  { icao: 'A319', class: 'narrowbody', wake: 'M', cruiseKts: 450, climbFpm: 2000, descentFpm: 1500, approachKts: 125, heavyCallsign: false },
+  { icao: 'A320', class: 'narrowbody', wake: 'M', cruiseKts: 450, climbFpm: 2000, descentFpm: 1500, approachKts: 130, heavyCallsign: false },
+  { icao: 'A321', class: 'narrowbody', wake: 'M', cruiseKts: 450, climbFpm: 1800, descentFpm: 1500, approachKts: 135, heavyCallsign: false },
+  { icao: 'B738', class: 'narrowbody', wake: 'M', cruiseKts: 455, climbFpm: 2000, descentFpm: 1500, approachKts: 135, heavyCallsign: false },
+  { icao: 'B39M', class: 'narrowbody', wake: 'M', cruiseKts: 455, climbFpm: 2000, descentFpm: 1500, approachKts: 135, heavyCallsign: false },
+  { icao: 'A333', class: 'widebody',   wake: 'H', cruiseKts: 480, climbFpm: 1800, descentFpm: 1200, approachKts: 140, heavyCallsign: 'heavy' },
+  { icao: 'A359', class: 'widebody',   wake: 'H', cruiseKts: 490, climbFpm: 1800, descentFpm: 1200, approachKts: 140, heavyCallsign: 'heavy' },
+  { icao: 'B77W', class: 'widebody',   wake: 'H', cruiseKts: 490, climbFpm: 1500, descentFpm: 1200, approachKts: 145, heavyCallsign: 'heavy' },
+  { icao: 'B788', class: 'widebody',   wake: 'H', cruiseKts: 485, climbFpm: 1800, descentFpm: 1200, approachKts: 140, heavyCallsign: 'heavy' },
+  { icao: 'B744', class: 'widebody',   wake: 'H', cruiseKts: 490, climbFpm: 1200, descentFpm: 1200, approachKts: 150, heavyCallsign: 'heavy' },
+  { icao: 'A388', class: 'widebody',   wake: 'J', cruiseKts: 490, climbFpm: 1200, descentFpm: 1000, approachKts: 145, heavyCallsign: 'super' },
+]
+
+export function simAircraftTypesByClass(cls: SimAircraftClass): SimAircraftType[] {
+  return SIM_AIRCRAFT_TYPES.filter(t => t.class === cls)
+}
+
+export function findSimAircraftType(icao: string): SimAircraftType | undefined {
+  return SIM_AIRCRAFT_TYPES.find(t => t.icao === icao.toUpperCase())
+}
diff --git a/shared/data/trafficTiers.ts b/shared/data/trafficTiers.ts
new file mode 100644
index 0000000..137ef9a
--- /dev/null
+++ b/shared/data/trafficTiers.ts
@@ -0,0 +1,102 @@
+/**
+ * How busy a frequency should sound: airport tier × time-of-day band → target
+ * number of simultaneously active simulated aircraft.
+ *
+ * There is no traffic-volume data source anywhere in the product (the airport
+ * API only returns frequencies), so this is a deliberately small, hand-curated
+ * model per the architecture design (§ 8). Order of resolution:
+ *   1. curated map → 2. heuristic over the already-loaded frequency list →
+ *   3. hard default 'regional', so the feature never falls flat on an unknown
+ *      airport, it is just moderately busy there.
+ */
+
+export type TrafficTier = 'major' | 'regional' | 'ga'
+
+/** Curated starting set — trivially extendable, no completeness claim. */
+export const AIRPORT_TRAFFIC_TIERS: Readonly<Record<string, TrafficTier>> = {
+  // Germany
+  EDDF: 'major', EDDM: 'major', EDDL: 'major', EDDB: 'major',
+  EDDH: 'regional', EDDK: 'regional', EDDS: 'regional', EDDV: 'regional',
+  EDDN: 'regional', EDDP: 'regional', EDDG: 'regional', EDDR: 'regional',
+  EDFE: 'ga', EDFH: 'ga', EDMA: 'ga', EDNY: 'ga', EDLW: 'ga', EDLP: 'ga',
+  // Europe
+  EHAM: 'major', EGLL: 'major', LFPG: 'major', LEMD: 'major', LEBL: 'major',
+  LIRF: 'major', LSZH: 'major', LOWW: 'major', EKCH: 'major', ESSA: 'major',
+  EGKK: 'regional', EGCC: 'regional', LFPO: 'regional', LIMC: 'regional',
+  LSGG: 'regional', EBBR: 'regional', LPPT: 'regional', EIDW: 'regional',
+  // Beyond
+  KJFK: 'major', KLAX: 'major', KORD: 'major', KATL: 'major',
+  OMDB: 'major', OTHH: 'major', RJTT: 'major', WSSS: 'major',
+}
+
+export const TRAFFIC_TIER_BASE: Readonly<Record<TrafficTier, number>> = {
+  major: 4,
+  regional: 2,
+  ga: 1,
+}
+
+/** Population cap — protects the speech queue and the TTS budget. */
+export const MAX_ACTIVE_TRAFFIC = 5
+
+/** The subset of frequency types the heuristic treats as a staffed ATC position. */
+const CONTROLLER_FREQ_TYPES = new Set(['DEL', 'CLD', 'GND', 'TWR', 'APP', 'DEP'])
+
+export interface TierHeuristicInput {
+  /** Frequency `type` codes already loaded for the airport (ATIS, GND, TWR, …). */
+  frequencyTypes: readonly string[]
+}
+
+/**
+ * Fallback when the airport isn't in the curated map: infer busy-ness from how
+ * many distinct controller positions the airport publishes. A field with
+ * Delivery + Ground + Tower + Approach/Departure is a major airport by any
+ * practical measure; a field with a Tower is at least regional.
+ */
+export function trafficTierFromFrequencies(input: TierHeuristicInput): TrafficTier {
+  const types = new Set(
+    input.frequencyTypes
+      .map(t => (t || '').toUpperCase().trim())
+      .filter(t => CONTROLLER_FREQ_TYPES.has(t)),
+  )
+  if (types.size >= 4) return 'major'
+  if (types.has('TWR')) return 'regional'
+  return 'ga'
+}
+
+/**
+ * Resolve the tier for an airport: curated map first, then the frequency
+ * heuristic, then the 'regional' default.
+ */
+export function resolveTrafficTier(
+  icao: string | undefined | null,
+  frequencyTypes: readonly string[] = [],
+): TrafficTier {
+  const key = (icao || '').toUpperCase().trim()
+  const curated = AIRPORT_TRAFFIC_TIERS[key]
+  if (curated) return curated
+  if (frequencyTypes.length) return trafficTierFromFrequencies({ frequencyTypes })
+  return 'regional'
+}
+
+/**
+ * Time-of-day multiplier in coarse bands. The user's local clock stands in for
+ * the airport's local time — training happens "on site" in practice, and a
+ * longitude-derived local time isn't worth the complexity in v1.
+ */
+export function timeOfDayFactor(localHour: number): number {
+  const h = Math.floor(localHour)
+  if (h >= 22 || h <= 5) return 0.2  // night
+  if (h >= 6 && h <= 9) return 1.3   // morning bank
+  if (h >= 10 && h <= 15) return 1.0 // day
+  if (h >= 16 && h <= 20) return 1.3 // evening bank
+  return 0.6                          // 21:00 — winding down
+}
+
+/**
+ * Target population of simultaneously active simulated aircraft.
+ * `ga` at night resolves to 0 — a dead GA frequency at 03:00 is correct.
+ */
+export function targetTrafficCount(tier: TrafficTier, localHour: number): number {
+  const raw = Math.round(TRAFFIC_TIER_BASE[tier] * timeOfDayFactor(localHour))
+  return Math.max(0, Math.min(MAX_ACTIVE_TRAFFIC, raw))
+}
diff --git a/shared/utils/aiTraffic/callsign.ts b/shared/utils/aiTraffic/callsign.ts
new file mode 100644
index 0000000..8814a2e
--- /dev/null
+++ b/shared/utils/aiTraffic/callsign.ts
@@ -0,0 +1,194 @@
+/**
+ * Callsign + type generation for simulated traffic, collision-free against the
+ * user's own callsign (architecture design § 1).
+ *
+ * "Collision-free" here means three escalating rules, because the failure mode
+ * is acoustic, not logical: the user must never think a call to someone else was
+ * meant for them.
+ *   1. exact   — never the user's callsign (long or short form)
+ *   2. prefix  — never the user's airline designator at all
+ *   3. phonetic— the spoken digit/letter tail must differ in at least two
+ *                positions, so DLH39A never shares a frequency with BAW39A
+ */
+
+import { DEFAULT_AIRLINE_TELEPHONY, normalizeRadioPhrase } from '../radioSpeech'
+import {
+  simAircraftTypesByClass,
+  type SimAircraftClass,
+  type SimAircraftType,
+} from '../../data/simAircraftTypes'
+import type { TrafficTier } from '../../data/trafficTiers'
+import type { Rng } from './rng'
+
+/**
+ * Only designators the radiotelephony normalizer already knows — an unknown one
+ * would be spelled out letter by letter instead of spoken as an airline name.
+ */
+export const TRAFFIC_AIRLINES: readonly string[] = Object.keys(DEFAULT_AIRLINE_TELEPHONY)
+
+/**
+ * German GA registrations used by the VFR flows in useLiveAtcSession — always
+ * blocked, since the user may be flying any of them.
+ */
+export const VFR_REGISTRATION_POOL: readonly string[] = [
+  'D-EMIL', 'D-EKLM', 'D-ENNY', 'D-ELLA', 'D-EOMT', 'D-ELPC', 'D-EMTO', 'D-EBRA',
+]
+
+const GA_LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+/** Type mix per tier — the weights are the design's § 1 percentages. */
+const TYPE_MIX: Readonly<Record<TrafficTier, readonly { value: SimAircraftClass; weight: number }[]>> = {
+  major:    [{ value: 'narrowbody', weight: 70 }, { value: 'widebody', weight: 20 }, { value: 'regional', weight: 10 }],
+  regional: [{ value: 'narrowbody', weight: 60 }, { value: 'regional', weight: 30 }, { value: 'ga', weight: 10 }],
+  ga:       [{ value: 'ga', weight: 80 }, { value: 'regional', weight: 20 }],
+}
+
+/** Levenshtein distance — small strings only, the naive DP is plenty. */
+export function levenshtein(a: string, b: string): number {
+  if (a === b) return 0
+  if (!a.length) return b.length
+  if (!b.length) return a.length
+
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      row[j] = Math.min(row[j - 1]! + 1, prev[j]! + 1, prev[j - 1]! + cost)
+    }
+    prev = row
+  }
+  return prev[b.length]!
+}
+
+/** The part a listener actually confuses: everything after the airline designator. */
+export function callsignTail(callsign: string): string {
+  const cs = (callsign || '').toUpperCase().replace(/[\s-]/g, '')
+  const airlineMatch = /^([A-Z]{3})([0-9].*)$/.exec(cs)
+  if (airlineMatch) return airlineMatch[2]!
+  // Registration (D-EMIL, N123AB): the tail is everything after the country prefix.
+  const regMatch = /^([A-Z])([A-Z0-9]+)$/.exec(cs)
+  if (regMatch) return regMatch[2]!
+  return cs
+}
+
+/** The airline designator, or '' for a registration. */
+export function callsignPrefix(callsign: string): string {
+  const cs = (callsign || '').toUpperCase().replace(/[\s-]/g, '')
+  const match = /^([A-Z]{3})[0-9]/.exec(cs)
+  return match ? match[1]! : ''
+}
+
+export interface CallsignBlocklist {
+  /** The user's callsign and short form, plus anything already spawned. */
+  callsigns: readonly string[]
+}
+
+/**
+ * Is `candidate` safe to put on the same frequency as everything in `blocked`?
+ * Implements the three rules above; exported so the rule itself is testable
+ * without driving the whole factory.
+ */
+export function isCallsignDistinct(candidate: string, blocked: readonly string[]): boolean {
+  const cand = (candidate || '').toUpperCase().replace(/[\s-]/g, '')
+  if (!cand) return false
+  const candPrefix = callsignPrefix(cand)
+  const candTail = callsignTail(cand)
+
+  for (const raw of blocked) {
+    const other = (raw || '').toUpperCase().replace(/[\s-]/g, '')
+    if (!other) continue
+    // 1. exact
+    if (cand === other) return false
+    // 2. prefix — no other aircraft from the user's airline at all
+    const otherPrefix = callsignPrefix(other)
+    if (candPrefix && otherPrefix && candPrefix === otherPrefix) return false
+    // 3. phonetic — the spoken tail must differ in at least two positions
+    if (levenshtein(candTail, callsignTail(other)) < 2) return false
+  }
+  return true
+}
+
+export interface CallsignFactoryOptions {
+  rng: Rng
+  tier: TrafficTier
+  /** The user's callsign and short form — always blocked. */
+  userCallsigns: readonly string[]
+}
+
+export interface GeneratedCallsign {
+  callsign: string
+  callsignSpoken: string
+  type: SimAircraftType
+}
+
+/** Spoken form: 'DLH472' + heavy → 'Lufthansa four seven two heavy'. */
+export function spokenCallsign(callsign: string, type: SimAircraftType): string {
+  const suffix = type.heavyCallsign ? ` ${type.heavyCallsign}` : ''
+  return normalizeRadioPhrase(`${callsign}${suffix}`, {
+    expandCallsigns: true,
+    airlineMap: DEFAULT_AIRLINE_TELEPHONY,
+  }).trim()
+}
+
+/**
+ * Generates callsign+type pairs that never collide with the user or with each
+ * other. Keeps its own issued list, so a factory instance is the pool's memory.
+ */
+export function createCallsignFactory(options: CallsignFactoryOptions) {
+  const { rng, tier, userCallsigns } = options
+  const issued: string[] = []
+
+  const permanentlyBlocked = [
+    ...userCallsigns,
+    // Any VFR registration the user could have been assigned.
+    ...VFR_REGISTRATION_POOL,
+  ].filter(Boolean)
+
+  const blockedNow = () => [...permanentlyBlocked, ...issued]
+
+  const rollType = (): SimAircraftType => {
+    const cls = rng.weighted(TYPE_MIX[tier])
+    const candidates = simAircraftTypesByClass(cls)
+    return rng.pick(candidates)
+  }
+
+  const rollAirlineCallsign = (): string => {
+    const airline = rng.pick(TRAFFIC_AIRLINES)
+    const digits = rng.int(1, 4)
+    let number = String(rng.int(1, 9))
+    for (let i = 1; i < digits; i++) number += String(rng.int(0, 9))
+    // A letter suffix on ~20% of flights, the way real schedules look.
+    const suffix = rng.chance(0.2) ? rng.pick(GA_LETTERS.split('')) : ''
+    return `${airline}${number}${suffix}`
+  }
+
+  const rollRegistration = (): string => {
+    let letters = ''
+    for (let i = 0; i < 3; i++) letters += rng.pick(GA_LETTERS.split(''))
+    return `D-E${letters}`
+  }
+
+  /**
+   * Returns null if no distinct callsign turned up within the attempt budget —
+   * the caller simply doesn't spawn this tick rather than risking a confusable
+   * one. With a 14-airline pool that effectively never happens.
+   */
+  const next = (): GeneratedCallsign | null => {
+    for (let attempt = 0; attempt < 60; attempt++) {
+      const type = rollType()
+      const callsign = type.class === 'ga' ? rollRegistration() : rollAirlineCallsign()
+      if (!isCallsignDistinct(callsign, blockedNow())) continue
+      issued.push(callsign)
+      return { callsign, callsignSpoken: spokenCallsign(callsign, type), type }
+    }
+    return null
+  }
+
+  const release = (callsign: string) => {
+    const index = issued.indexOf(callsign)
+    if (index >= 0) issued.splice(index, 1)
+  }
+
+  return { next, release, issued: () => [...issued] }
+}
diff --git a/shared/utils/aiTraffic/gating.ts b/shared/utils/aiTraffic/gating.ts
new file mode 100644
index 0000000..04dc141
--- /dev/null
+++ b/shared/utils/aiTraffic/gating.ts
@@ -0,0 +1,99 @@
+/**
+ * The gating chain (architecture design § 3, Frage 10) — the hard "traffic never
+ * talks over the user" guarantee, as one pure function.
+ *
+ * Evaluated at TWO points: before enqueuing a traffic pair, and again inside the
+ * speech task when it actually starts playing. Seconds can pass between the two,
+ * and a gate that was open at enqueue time means nothing at playback time.
+ *
+ * "Only one transmitter at a time" is handled structurally elsewhere — traffic
+ * runs through the same serial speech queue as real ATC. This chain answers the
+ * different question of *whether the frequency belongs to the user right now*.
+ */
+
+/**
+ * How long after an ATC instruction the frequency stays reserved for the user's
+ * readback. Taken literally, `backendExpectedPhrase` is set almost permanently
+ * (the flow alternates ATC/pilot states), which would mute traffic forever and
+ * make the feature pointless. So the lock protects the *fresh* readback window
+ * instead: absolute silence from the moment ATC speaks until the user answers,
+ * but at least this long. After it, ambient chatter may resume — a real
+ * frequency also keeps working when a pilot dawdles, and the flow's own silence
+ * timer runs independently of this.
+ *
+ * Set it to Infinity for the literal-strict reading: same chain, one parameter,
+ * no second code path.
+ */
+export const DEFAULT_READBACK_PROTECTION_MS = 12_000
+
+export interface ReadbackWindow {
+  /** Role of the flow state the session is currently on. */
+  currentStateRole: 'pilot' | 'atc' | 'system' | undefined
+  /** The backend's authoritative expected pilot phrase, if it wants one. */
+  backendExpectedPhrase: string | null
+  /** When the ATC instruction that opened this window was spoken (epoch ms). */
+  lastControllerSpeechAtMs: number | null
+  nowMs: number
+  readbackProtectionMs?: number
+}
+
+/**
+ * True while ATC is still owed a fresh readback from the user.
+ *
+ * Both base signals must hold — the flow is on a pilot state AND the backend
+ * actually named a phrase it expects — and the protection window must still be
+ * open. Once the window lapses the user is simply taking their time, which is
+ * not a reason to keep the whole frequency silent.
+ */
+export function readbackPending(win: ReadbackWindow): boolean {
+  if (win.currentStateRole !== 'pilot') return false
+  if (!win.backendExpectedPhrase) return false
+  if (win.lastControllerSpeechAtMs === null) return false
+
+  const protectionMs = win.readbackProtectionMs ?? DEFAULT_READBACK_PROTECTION_MS
+  if (protectionMs === Number.POSITIVE_INFINITY) return true
+  return win.nowMs - win.lastControllerSpeechAtMs < protectionMs
+}
+
+export interface GateInput {
+  /** The settings toggle. */
+  aiTrafficEnabled: boolean
+  /** The user is holding PTT — absolute, no window, no exception. */
+  isRecording: boolean
+  /** A user transmission is waiting on the backend — equally absolute. */
+  transmitInFlight: boolean
+  /** True while the session exists and the monitor screen is up. */
+  sessionActive: boolean
+  readback: ReadbackWindow
+}
+
+export type GateBlockReason =
+  | 'disabled'
+  | 'recording'
+  | 'transmit_in_flight'
+  | 'readback_pending'
+  | 'session_inactive'
+
+export interface GateResult {
+  open: boolean
+  /** Why it's shut — surfaced in the debug log, and what the tests assert on. */
+  reason?: GateBlockReason
+}
+
+/**
+ * The chain itself. Ordered so the reason reported is the most specific one:
+ * a disabled toggle outranks everything, then the two absolute user-owns-the-
+ * frequency signals, then the softer readback window.
+ */
+export function evaluateGate(input: GateInput): GateResult {
+  if (!input.aiTrafficEnabled) return { open: false, reason: 'disabled' }
+  if (input.isRecording) return { open: false, reason: 'recording' }
+  if (input.transmitInFlight) return { open: false, reason: 'transmit_in_flight' }
+  if (!input.sessionActive) return { open: false, reason: 'session_inactive' }
+  if (readbackPending(input.readback)) return { open: false, reason: 'readback_pending' }
+  return { open: true }
+}
+
+export function gateOpen(input: GateInput): boolean {
+  return evaluateGate(input).open
+}
diff --git a/shared/utils/aiTraffic/instructions.ts b/shared/utils/aiTraffic/instructions.ts
new file mode 100644
index 0000000..73c666a
--- /dev/null
+++ b/shared/utils/aiTraffic/instructions.ts
@@ -0,0 +1,549 @@
+/**
+ * The rule-based instruction planner (architecture design § 3, Fragen 4 + the
+ * decision table). Zero LLM calls: every instruction the simulated traffic ever
+ * receives is a finite, parameterised template — variance comes from the seeded
+ * RNG picking between template variants, not from generation.
+ */
+
+import type { SimAircraftType } from '../../data/simAircraftTypes'
+import type { Rng } from './rng'
+import {
+  DIRECT_HEADROOM_FACTOR,
+  TERMINAL_STANDARD_NM,
+  assessInTrail,
+  departureWakeDelaySec,
+  slotIsFree,
+} from './separation'
+import type { SimAircraft, SimPhase } from './types'
+
+/**
+ * Discrete speed steps a controller actually assigns, fastest first. The final
+ * rung is the type's own approach speed ("reduce to final approach speed"), so
+ * the usable ladder depends on the aircraft — see `speedLadderFor`.
+ */
+export const SPEED_LADDER: readonly number[] = [250, 220, 210, 190, 180, 170, 160]
+
+/** Below this altitude 250 kt IAS is the ceiling for jets. */
+export const SPEED_LIMIT_ALTITUDE_FT = 10000
+export const SPEED_LIMIT_BELOW_KTS = 250
+
+/** Phases in which an approach speed reduction makes any sense. */
+const SPEED_CONTROL_PHASES: readonly SimPhase[] = ['inbound', 'approach']
+
+/** Vectoring delay booked on the timeline instead of flying the turn geometrically. */
+export const VECTOR_DELAY_MIN_SEC = 60
+export const VECTOR_DELAY_MAX_SEC = 120
+
+/**
+ * The rungs available for one type: the fixed ladder down to its approach
+ * speed, which is itself the last rung. A type whose Vref sits above a rung
+ * simply never sees that rung.
+ */
+export function speedLadderFor(type: SimAircraftType): number[] {
+  return [...SPEED_LADDER.filter(step => step > type.approachKts), type.approachKts]
+}
+
+/**
+ * The next speed a controller may assign, or null when there is nothing legal
+ * and useful left to say. Implements all four rules from the design at once:
+ * one step per instruction, never above 250 below 10,000 ft, never below the
+ * type's Vref, and never in a phase where it would be nonsense.
+ */
+export function nextSpeedStep(
+  aircraft: Pick<SimAircraft, 'phase' | 'altitudeFt' | 'iasKts' | 'assignedSpeedKts' | 'type'>,
+): number | null {
+  // A Cessna gets no jet speed callouts at all — see slowestPracticalSpeech().
+  if (aircraft.type.wake === 'L') return null
+  if (!SPEED_CONTROL_PHASES.includes(aircraft.phase)) return null
+
+  const current = aircraft.assignedSpeedKts ?? aircraft.iasKts
+  const ceiling = aircraft.altitudeFt < SPEED_LIMIT_ALTITUDE_FT ? SPEED_LIMIT_BELOW_KTS : Infinity
+
+  const candidate = speedLadderFor(aircraft.type).find(step => step < current && step <= ceiling)
+  return candidate ?? null
+}
+
+/** True once speed control has nothing left to give and only a vector remains. */
+export function isAtMinimumSpeed(
+  aircraft: Pick<SimAircraft, 'phase' | 'altitudeFt' | 'iasKts' | 'assignedSpeedKts' | 'type'>,
+): boolean {
+  return nextSpeedStep(aircraft) === null
+}
+
+export interface DirectValidation {
+  valid: boolean
+  /** Index of the target fix in the remaining route (only when valid). */
+  fixIndex?: number
+  fix?: string
+  /** NM the shortcut saves — used to keep distanceToFieldNm consistent. */
+  savedNm?: number
+  reason?: 'behind' | 'not_on_route' | 'no_headroom' | 'wrong_phase' | 'gap_conflict'
+}
+
+export interface DirectContext {
+  /** Gap to the aircraft ahead, in NM. Infinity when there is nobody ahead. */
+  gapNm: number
+  requiredNm: number
+  /** How much distance each skipped fix removes from the remaining route. */
+  nmPerFix: number
+}
+
+/**
+ * A direct is only ever a *reward* for a quiet picture, never a conflict
+ * resolver — so it must be strictly ahead on the route, and the shortened
+ * timeline must still respect the in-trail minimum afterwards. Failing either,
+ * it is simply not generated.
+ */
+export function validateDirect(
+  aircraft: Pick<SimAircraft, 'phase' | 'routeFixes'>,
+  fix: string,
+  ctx: DirectContext,
+): DirectValidation {
+  if (aircraft.phase !== 'inbound' && aircraft.phase !== 'approach') {
+    return { valid: false, reason: 'wrong_phase' }
+  }
+  const index = aircraft.routeFixes.indexOf(fix)
+  if (index < 0) return { valid: false, reason: 'not_on_route' }
+  // Index 0 is the fix the aircraft is already proceeding to — "direct" to it is
+  // a no-op, and anything at a lower index has been passed.
+  if (index === 0) return { valid: false, reason: 'behind' }
+
+  const savedNm = index * ctx.nmPerFix
+  if (ctx.gapNm < ctx.requiredNm * DIRECT_HEADROOM_FACTOR) {
+    return { valid: false, reason: 'no_headroom' }
+  }
+  // The shortcut eats into the gap to whoever is ahead — never issue one that
+  // busts the minimum the moment it is read back.
+  if (ctx.gapNm - savedNm < ctx.requiredNm) {
+    return { valid: false, reason: 'gap_conflict' }
+  }
+  return { valid: true, fixIndex: index, fix, savedNm }
+}
+
+/** Apply an accepted direct to the aircraft state, so later phraseology stays consistent. */
+export function applyDirect(aircraft: SimAircraft, validation: DirectValidation): void {
+  if (!validation.valid || validation.fixIndex === undefined) return
+  aircraft.routeFixes.splice(0, validation.fixIndex)
+  aircraft.distanceToFieldNm = Math.max(0, aircraft.distanceToFieldNm - (validation.savedNm ?? 0))
+}
+
+// ── The decision table ────────────────────────────────────────────────────────
+
+export type InstructionKind =
+  | 'phase'
+  | 'slot_hold'
+  | 'wake_hold'
+  | 'speed'
+  | 'vector'
+  | 'direct'
+  | 'handover'
+  | 'ambient'
+
+export interface InstructionPlan {
+  kind: InstructionKind
+  callsign: string
+  /** Speed instructions only. */
+  speedKts?: number
+  /** Vector instructions only. */
+  headingDeg?: number
+  vectorDelaySec?: number
+  /** Direct instructions only. */
+  direct?: DirectValidation
+  /** Handover instructions only. */
+  handoverStation?: string
+  handoverFrequency?: string
+  /** Wake/slot holds only — how long the aircraft is held. */
+  holdSec?: number
+}
+
+/**
+ * How long an aircraft is left alone after each kind of instruction — roughly
+ * how long the instruction takes to actually change the picture. The one source
+ * of truth for `SimAircraft.quietUntilSec`, shared by the scheduler and tests.
+ */
+export function cooldownSecFor(plan: InstructionPlan): number {
+  switch (plan.kind) {
+    // Let the aircraft decelerate before judging the gap again — IAS moves at
+    // ~1 kt/s, so a 20 kt step needs ~20 s before it means anything.
+    case 'speed': return 30
+    // Fly the vector out, then a beat before "resume own navigation".
+    case 'vector': return (plan.vectorDelaySec ?? 90) + 30
+    // A treat, not a habit.
+    case 'direct': return 120
+    case 'wake_hold': return plan.holdSec ?? 60
+    case 'slot_hold': return 45
+    // It is leaving the frequency; there is nothing more to say to it.
+    case 'handover': return Number.POSITIVE_INFINITY
+    case 'ambient': return 90
+    // The phase timeline (nextEventAtSec) already paces these.
+    case 'phase': return 15
+    default: return 30
+  }
+}
+
+export interface PlannerContext {
+  nowSec: number
+  rng: Rng
+  /** The aircraft immediately ahead on the approach, if any. */
+  leader: Pick<SimAircraft, 'distanceToFieldNm' | 'type'> | null
+  /** Everything currently reserving the runway, including the user's slot. */
+  occupiedSlots: readonly { fromSec: number; toSec: number }[]
+  /** The departure that most recently used the runway, for the wake timer. */
+  lastDeparture: { type: SimAircraftType; atSec: number } | null
+  /** Where this aircraft is handed to next, if it has reached a sector boundary. */
+  handover: { station: string; frequency: string } | null
+  /** NM each remaining fix represents — used for direct headroom. */
+  nmPerFix: number
+  /** How long the tuned frequency has been silent, for ambient chatter. */
+  silentForSec: number
+  /** Seeded threshold (45–90 s) above which ambient chatter may fire. */
+  ambientAfterSec: number
+}
+
+function inTrailGap(aircraft: SimAircraft, ctx: PlannerContext) {
+  if (!ctx.leader) {
+    return {
+      gapNm: Number.POSITIVE_INFINITY,
+      requiredNm: TERMINAL_STANDARD_NM,
+      needsAction: false,
+      violated: false,
+      gapSec: Number.POSITIVE_INFINITY,
+    }
+  }
+  return assessInTrail({
+    leaderDistanceNm: ctx.leader.distanceToFieldNm,
+    leaderWake: ctx.leader.type.wake,
+    followerDistanceNm: aircraft.distanceToFieldNm,
+    followerWake: aircraft.type.wake,
+    followerKts: aircraft.iasKts,
+  })
+}
+
+/**
+ * The design's rule table, evaluated per tick — first matching row wins.
+ * Returns null when this aircraft has nothing to say right now.
+ */
+export function planInstruction(aircraft: SimAircraft, ctx: PlannerContext): InstructionPlan | null {
+  const { rng } = ctx
+
+  // One thing at a time. Most rows below test a condition that stays true until
+  // the instruction has had time to work (a vector is still being flown, a wake
+  // timer is still running), so without this the same row fires every tick and
+  // the controller nags one aircraft into the ground.
+  if (ctx.nowSec < aircraft.quietUntilSec) return null
+
+  // Row 7 (sector boundary) is checked first among the event-driven rows: a
+  // handover is the reason the phase timer fired in the first place.
+  if (ctx.handover && aircraft.nextEventAtSec <= ctx.nowSec) {
+    return {
+      kind: 'handover',
+      callsign: aircraft.callsign,
+      handoverStation: ctx.handover.station,
+      handoverFrequency: ctx.handover.frequency,
+    }
+  }
+
+  // Row 3 — departure behind a heavy: the wake timer outranks the runway slot,
+  // because it is the reason the slot has to move.
+  if (aircraft.phase === 'lineup' && ctx.lastDeparture) {
+    const required = departureWakeDelaySec(ctx.lastDeparture.type.wake, aircraft.type.wake)
+    const elapsed = ctx.nowSec - ctx.lastDeparture.atSec
+    if (required > 0 && elapsed < required) {
+      return { kind: 'wake_hold', callsign: aircraft.callsign, holdSec: Math.ceil(required - elapsed) }
+    }
+  }
+
+  // Row 2 — the runway slot collides with the user's reservation or another
+  // aircraft's. Simulated traffic always yields.
+  //
+  // The aircraft's own reservation is in ctx.occupiedSlots (the caller passes the
+  // whole runway timeline), so it has to come out first — otherwise every
+  // aircraft conflicts with itself, forever, and holds instead of ever flying.
+  if (aircraft.runwaySlot) {
+    const others = ctx.occupiedSlots.filter(slot => slot !== aircraft.runwaySlot)
+    if (!slotIsFree(aircraft.runwaySlot, others)) {
+      return { kind: 'slot_hold', callsign: aircraft.callsign }
+    }
+  }
+
+  // Row 1 — a phase change came due.
+  if (aircraft.nextEventAtSec <= ctx.nowSec && aircraft.phase !== 'handed_off') {
+    return { kind: 'phase', callsign: aircraft.callsign }
+  }
+
+  const gap = inTrailGap(aircraft, ctx)
+
+  // Row 4 — closing up, but speed control still has a step left.
+  if (gap.needsAction) {
+    const step = nextSpeedStep(aircraft)
+    if (step !== null) {
+      return { kind: 'speed', callsign: aircraft.callsign, speedKts: step }
+    }
+    // Row 5 — minimum busted and already at the slowest practical speed.
+    if (gap.violated) {
+      return {
+        kind: 'vector',
+        callsign: aircraft.callsign,
+        headingDeg: rng.int(1, 36) * 10,
+        vectorDelaySec: rng.int(VECTOR_DELAY_MIN_SEC, VECTOR_DELAY_MAX_SEC),
+      }
+    }
+  }
+
+  // Row 6 — lots of air, a valid fix ahead, and the dice agree (rarely).
+  if (aircraft.routeFixes.length > 1 && rng.chance(0.04)) {
+    const fix = aircraft.routeFixes[aircraft.routeFixes.length - 1]!
+    const direct = validateDirect(aircraft, fix, {
+      gapNm: gap.gapNm,
+      requiredNm: gap.requiredNm,
+      nmPerFix: ctx.nmPerFix,
+    })
+    if (direct.valid) {
+      return { kind: 'direct', callsign: aircraft.callsign, direct }
+    }
+  }
+
+  // Row 8 — nothing to do and the frequency has been quiet for a while.
+  if (ctx.silentForSec >= ctx.ambientAfterSec) {
+    return { kind: 'ambient', callsign: aircraft.callsign }
+  }
+
+  return null
+}
+
+// ── Phraseology ───────────────────────────────────────────────────────────────
+
+export interface RadioEvent {
+  kind: InstructionKind
+  callsign: string
+  /** What the controller says. */
+  atcText: string
+  /** What the simulated pilot reads back — spoken in that aircraft's own voice. */
+  pilotReadbackText: string
+  /**
+   * Who keys first. Every instruction is ATC-first; an ambient check-in is the
+   * one event the aircraft initiates, and playing it the other way round would
+   * sound like the controller talking to nobody.
+   */
+  order: 'atc_first' | 'pilot_first'
+  /** State mutation to apply once the pair has actually been spoken. */
+  plan: InstructionPlan
+}
+
+export interface RenderContext {
+  rng: Rng
+  /** e.g. 'Frankfurt Approach' — the station the traffic is talking to. */
+  station: string
+  runway: string
+}
+
+const pick = (rng: Rng, variants: readonly string[]) => rng.pick(variants)
+
+/** GA aircraft never get a numeric jet speed — this is what they get instead. */
+function slowestPracticalSpeech(callsign: string, rng: Rng): { atc: string; readback: string } {
+  return {
+    atc: pick(rng, [
+      `${callsign}, reduce to slowest practical speed`,
+      `${callsign}, make your approach speed as slow as practical`,
+    ]),
+    readback: `Slowest practical speed, ${callsign}`,
+  }
+}
+
+function phaseSpeech(aircraft: SimAircraft, ctx: RenderContext): { atc: string; readback: string } {
+  const { rng, runway } = ctx
+  const cs = aircraft.callsign
+  const miles = Math.max(1, Math.round(aircraft.distanceToFieldNm))
+  switch (aircraft.phase) {
+    case 'inbound':
+      return {
+        atc: pick(rng, [
+          `${cs}, descend to altitude 4000 feet, QNH 1013`,
+          `${cs}, descend altitude 5000 feet, expect ILS approach runway ${runway}`,
+        ]),
+        readback: `Descend 4000 feet, ${cs}`,
+      }
+    case 'approach':
+      return {
+        atc: pick(rng, [
+          `${cs}, ${miles} miles from touchdown, cleared ILS approach runway ${runway}`,
+          `${cs}, turn right heading 250, cleared ILS approach runway ${runway}`,
+        ]),
+        readback: `Cleared ILS approach runway ${runway}, ${cs}`,
+      }
+    case 'final':
+      return {
+        atc: pick(rng, [
+          `${cs}, wind 250 degrees 8 knots, runway ${runway}, cleared to land`,
+          `${cs}, runway ${runway}, cleared to land, wind 240 degrees 6 knots`,
+        ]),
+        readback: `Cleared to land runway ${runway}, ${cs}`,
+      }
+    case 'rollout':
+      return {
+        atc: pick(rng, [
+          `${cs}, vacate via taxiway November, contact Ground 121.800`,
+          `${cs}, turn right when able, contact Ground 121.800`,
+        ]),
+        readback: `Ground 121.800, ${cs}`,
+      }
+    case 'taxi_out':
+      return {
+        atc: pick(rng, [
+          `${cs}, taxi to holding point runway ${runway} via taxiway November`,
+          `${cs}, taxi holding point runway ${runway}, give way to the A320 from your right`,
+        ]),
+        readback: `Taxi holding point runway ${runway}, ${cs}`,
+      }
+    case 'lineup':
+      return {
+        atc: pick(rng, [
+          `${cs}, runway ${runway}, line up and wait`,
+          `${cs}, behind the landing traffic, line up and wait runway ${runway}`,
+        ]),
+        readback: `Line up and wait runway ${runway}, ${cs}`,
+      }
+    case 'takeoff':
+      return {
+        atc: pick(rng, [
+          `${cs}, wind 250 degrees 8 knots, runway ${runway}, cleared for takeoff`,
+          `${cs}, runway ${runway}, cleared for takeoff, wind 240 degrees 7 knots`,
+        ]),
+        readback: `Cleared for takeoff runway ${runway}, ${cs}`,
+      }
+    case 'climbout':
+      return {
+        atc: pick(rng, [
+          `${cs}, climb to altitude 6000 feet`,
+          `${cs}, continue climb altitude 5000 feet, resume own navigation`,
+        ]),
+        readback: `Climb 6000 feet, ${cs}`,
+      }
+    default:
+      return { atc: `${cs}, roger`, readback: `${cs}` }
+  }
+}
+
+function ambientSpeech(aircraft: SimAircraft, ctx: RenderContext): { atc: string; readback: string } {
+  const { rng, station } = ctx
+  const cs = aircraft.callsign
+  const miles = Math.max(1, Math.round(aircraft.distanceToFieldNm))
+  // Row 8: the aircraft checks in and the controller answers — the pair is
+  // emitted pilot-first (see RadioEvent.order).
+  return rng.pick([
+    {
+      readback: `${station}, ${cs}, passing altitude 7000 feet, information Kilo`,
+      atc: `${cs}, ${station}, radar contact, continue as cleared`,
+    },
+    {
+      readback: `${station}, ${cs}, ${miles} miles to run`,
+      atc: `${cs}, ${station}, roger, no reported traffic ahead`,
+    },
+    {
+      readback: `${station}, ${cs}, with you, descending altitude 5000 feet`,
+      atc: `${cs}, ${station}, identified, expect vectors ILS runway ${ctx.runway}`,
+    },
+  ])
+}
+
+/** Turn a plan into the ATC call + the simulated pilot's readback. */
+export function renderInstruction(
+  aircraft: SimAircraft,
+  plan: InstructionPlan,
+  ctx: RenderContext,
+): RadioEvent {
+  const { rng, station, runway } = ctx
+  const cs = aircraft.callsign
+  let atcText: string
+  let pilotReadbackText: string
+
+  switch (plan.kind) {
+    case 'speed': {
+      if (aircraft.type.wake === 'L') {
+        const speech = slowestPracticalSpeech(cs, rng)
+        atcText = speech.atc
+        pilotReadbackText = speech.readback
+        break
+      }
+      atcText = pick(rng, [
+        `${cs}, reduce speed to ${plan.speedKts} knots`,
+        `${cs}, for spacing reduce speed to ${plan.speedKts} knots`,
+        `${cs}, speed ${plan.speedKts} knots or less`,
+      ])
+      pilotReadbackText = `Speed ${plan.speedKts} knots, ${cs}`
+      break
+    }
+    case 'vector': {
+      atcText = pick(rng, [
+        `${cs}, turn left heading ${plan.headingDeg}, vectors for spacing`,
+        `${cs}, turn right heading ${plan.headingDeg}, vectors for sequencing`,
+      ])
+      pilotReadbackText = `Heading ${plan.headingDeg}, ${cs}`
+      break
+    }
+    case 'direct': {
+      const fix = plan.direct?.fix ?? aircraft.routeFixes[0] ?? 'the field'
+      atcText = pick(rng, [
+        `${cs}, proceed direct ${fix}`,
+        `${cs}, when ready proceed direct ${fix}`,
+      ])
+      pilotReadbackText = `Direct ${fix}, ${cs}`
+      break
+    }
+    case 'handover': {
+      atcText = pick(rng, [
+        `${cs}, contact ${plan.handoverStation} ${plan.handoverFrequency}, good day`,
+        `${cs}, contact ${plan.handoverStation} on ${plan.handoverFrequency}, bye bye`,
+      ])
+      pilotReadbackText = `${plan.handoverFrequency}, ${cs}, good day`
+      break
+    }
+    case 'wake_hold': {
+      atcText = pick(rng, [
+        `${cs}, hold position, wake turbulence delay`,
+        `${cs}, hold short runway ${runway}, wake turbulence separation`,
+      ])
+      pilotReadbackText = `Holding, ${cs}`
+      break
+    }
+    case 'slot_hold': {
+      const arriving = aircraft.phase === 'inbound' || aircraft.phase === 'approach' || aircraft.phase === 'final'
+      if (arriving) {
+        atcText = pick(rng, [
+          `${cs}, continue approach, expect late landing clearance`,
+          `${cs}, continue approach runway ${runway}, landing clearance to follow`,
+        ])
+        pilotReadbackText = `Continue approach, ${cs}`
+      } else {
+        atcText = pick(rng, [
+          `${cs}, hold position, traffic on the runway`,
+          `${cs}, hold short runway ${runway}, one landing ahead of you`,
+        ])
+        pilotReadbackText = `Holding short runway ${runway}, ${cs}`
+      }
+      break
+    }
+    case 'ambient': {
+      const speech = ambientSpeech(aircraft, ctx)
+      atcText = speech.atc
+      pilotReadbackText = speech.readback
+      break
+    }
+    case 'phase':
+    default: {
+      const speech = phaseSpeech(aircraft, ctx)
+      atcText = speech.atc
+      pilotReadbackText = speech.readback
+      break
+    }
+  }
+
+  return {
+    kind: plan.kind,
+    callsign: cs,
+    atcText,
+    pilotReadbackText,
+    order: plan.kind === 'ambient' ? 'pilot_first' : 'atc_first',
+    plan,
+  }
+}
diff --git a/shared/utils/aiTraffic/rng.ts b/shared/utils/aiTraffic/rng.ts
new file mode 100644
index 0000000..ea1449c
--- /dev/null
+++ b/shared/utils/aiTraffic/rng.ts
@@ -0,0 +1,72 @@
+/**
+ * Seeded RNG for the simulated background traffic. Everything random about the
+ * traffic — callsigns, type mix, timing jitter, template variants — runs through
+ * one of these, so a session is reproducible from its seed alone. That keeps bug
+ * reports actionable and lets the sim core be tested without mocking anything
+ * (architecture design § 0).
+ */
+
+import { fnv1a } from '../voicePool'
+
+export interface Rng {
+  /** Uniform in [0, 1). */
+  next(): number
+  /** Uniform integer in [min, max] (inclusive). */
+  int(min: number, max: number): number
+  /** Uniform float in [min, max). */
+  float(min: number, max: number): number
+  /** Uniform element. Throws on an empty list. */
+  pick<T>(items: readonly T[]): T
+  /** True with probability `p`. */
+  chance(p: number): boolean
+  /**
+   * Element picked by relative weight. Weights must be non-negative and sum > 0.
+   */
+  weighted<T>(entries: readonly { value: T; weight: number }[]): T
+}
+
+/** mulberry32 — 32-bit state, good distribution, five lines. */
+export function createRng(seed: string | number): Rng {
+  let state = (typeof seed === 'number' ? seed >>> 0 : fnv1a(seed)) >>> 0
+  // A zero state degenerates mulberry32 into a constant stream.
+  if (state === 0) state = 0x9e3779b9
+
+  const next = (): number => {
+    state = (state + 0x6d2b79f5) >>> 0
+    let t = state
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+
+  const rng: Rng = {
+    next,
+    int: (min, max) => Math.floor(next() * (max - min + 1)) + min,
+    float: (min, max) => min + next() * (max - min),
+    pick: <T>(items: readonly T[]): T => {
+      if (!items.length) throw new Error('Rng.pick: empty list')
+      return items[Math.floor(next() * items.length)]!
+    },
+    chance: p => next() < p,
+    weighted: <T>(entries: readonly { value: T; weight: number }[]): T => {
+      const total = entries.reduce((sum, e) => sum + Math.max(0, e.weight), 0)
+      if (!entries.length || total <= 0) throw new Error('Rng.weighted: no positive weights')
+      let roll = next() * total
+      for (const entry of entries) {
+        roll -= Math.max(0, entry.weight)
+        if (roll < 0) return entry.value
+      }
+      return entries[entries.length - 1]!.value
+    },
+  }
+  return rng
+}
+
+/**
+ * The session seed: session id + calendar day. Same session on the same day
+ * replays identically; a new session gets fresh traffic.
+ */
+export function trafficSeed(sessionId: string, date: Date = new Date()): string {
+  const day = `${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`
+  return `${sessionId}|${day}`
+}
diff --git a/shared/utils/aiTraffic/separation.ts b/shared/utils/aiTraffic/separation.ts
new file mode 100644
index 0000000..20c2b93
--- /dev/null
+++ b/shared/utils/aiTraffic/separation.ts
@@ -0,0 +1,137 @@
+/**
+ * Separation rules for the simulated traffic (architecture design § 3, Frage 2).
+ *
+ * Two invariants, checked every tick:
+ *   - in-trail gap on a shared approach path: max(terminal standard, wake matrix)
+ *   - runway occupancy: never two clearances with overlapping slots
+ *
+ * The user's aircraft is never a simulated position — it is a slot reservation
+ * that simulated traffic always yields to. A conflict therefore always resolves
+ * by slowing, vectoring or holding the *simulated* aircraft.
+ */
+
+import type { WakeCategory } from '../../data/simAircraftTypes'
+import type { RunwaySlot } from './types'
+
+/** Radar separation in the terminal area, before any wake supplement. */
+export const TERMINAL_STANDARD_NM = 3
+
+/** Buffer on top of the requirement at which the planner starts acting. */
+export const SPACING_TRIGGER_FACTOR = 1.2
+
+/** Gap above which a direct becomes a plausible reward rather than a risk. */
+export const DIRECT_HEADROOM_FACTOR = 2
+
+/**
+ * Required in-trail distance, leader → follower, on the same approach track.
+ * These are absolute minima in NM (not supplements): a Medium behind a Heavy
+ * needs 5 NM rather than the standard 3. Pairs with no entry are covered by the
+ * terminal standard alone.
+ */
+const WAKE_MATRIX: Readonly<Partial<Record<WakeCategory, Partial<Record<WakeCategory, number>>>>> = {
+  J: { H: 6, M: 7, L: 8 },
+  H: { H: 4, M: 5, L: 6 },
+  M: { L: 5 },
+  L: {},
+}
+
+/** The wake-derived minimum for a pair, or 0 when the category needs no supplement. */
+export function wakeSeparationNm(leader: WakeCategory, follower: WakeCategory): number {
+  return WAKE_MATRIX[leader]?.[follower] ?? 0
+}
+
+/** What the follower actually has to hold: the stricter of standard and wake. */
+export function requiredGapNm(leader: WakeCategory, follower: WakeCategory): number {
+  return Math.max(TERMINAL_STANDARD_NM, wakeSeparationNm(leader, follower))
+}
+
+/** Convert a distance gap into the time it buys at the follower's speed. */
+export function gapToTimeSec(gapNm: number, groundspeedKts: number): number {
+  if (groundspeedKts <= 0) return Number.POSITIVE_INFINITY
+  return (gapNm / groundspeedKts) * 3600
+}
+
+/** Act before the minimum is actually busted — the 20% buffer from the design. */
+export function needsSpacing(gapNm: number, required: number): boolean {
+  return gapNm < required * SPACING_TRIGGER_FACTOR
+}
+
+/** The minimum is (or is about to be) busted and speed alone won't fix it. */
+export function isGapViolated(gapNm: number, required: number): boolean {
+  return gapNm < required
+}
+
+/**
+ * Time-based departure wake separation: a Light/Medium behind a Heavy/Super
+ * waits ~3 minutes, a Heavy behind a Heavy ~2. Same-category non-heavy pairs are
+ * separated by runway occupancy alone, not by time.
+ */
+export function departureWakeDelaySec(leader: WakeCategory, follower: WakeCategory): number {
+  const leaderIsHeavy = leader === 'H' || leader === 'J'
+  if (!leaderIsHeavy) return 0
+  const followerIsHeavy = follower === 'H' || follower === 'J'
+  return followerIsHeavy ? 120 : 180
+}
+
+export function slotsOverlap(a: RunwaySlot, b: RunwaySlot): boolean {
+  return a.fromSec < b.toSec && b.fromSec < a.toSec
+}
+
+export function slotIsFree(candidate: RunwaySlot, occupied: readonly RunwaySlot[]): boolean {
+  return !occupied.some(slot => slotsOverlap(candidate, slot))
+}
+
+/**
+ * Push `desired` later until it clears everything in `occupied`, preserving its
+ * duration. Simulated traffic always yields, so this only ever moves forward.
+ */
+export function nextFreeSlot(desired: RunwaySlot, occupied: readonly RunwaySlot[]): RunwaySlot {
+  const duration = desired.toSec - desired.fromSec
+  let from = desired.fromSec
+  // Each pass can only be blocked by a slot that ends later than the last one we
+  // cleared, so the loop is bounded by the number of occupied slots.
+  for (let pass = 0; pass <= occupied.length; pass++) {
+    const candidate = { fromSec: from, toSec: from + duration }
+    const blocker = occupied.find(slot => slotsOverlap(candidate, slot))
+    if (!blocker) return candidate
+    from = blocker.toSec
+  }
+  return { fromSec: from, toSec: from + duration }
+}
+
+export interface InTrailPair {
+  /** Distance to the field of the aircraft ahead, in NM. */
+  leaderDistanceNm: number
+  leaderWake: WakeCategory
+  followerDistanceNm: number
+  followerWake: WakeCategory
+  /** Follower's current speed — turns the distance gap into a closing rate. */
+  followerKts: number
+}
+
+export interface InTrailAssessment {
+  gapNm: number
+  requiredNm: number
+  /** Within the 20% buffer: start reducing speed. */
+  needsAction: boolean
+  /** Minimum busted: speed is no longer enough. */
+  violated: boolean
+  /** How long the current gap lasts at the follower's speed. */
+  gapSec: number
+}
+
+/**
+ * The one place the in-trail invariant is evaluated. Distances are 1D along the
+ * approach: the follower is further from the field than the leader.
+ */
+export function assessInTrail(pair: InTrailPair): InTrailAssessment {
+  const gapNm = Math.max(0, pair.followerDistanceNm - pair.leaderDistanceNm)
+  const requiredNm = requiredGapNm(pair.leaderWake, pair.followerWake)
+  return {
+    gapNm,
+    requiredNm,
+    needsAction: needsSpacing(gapNm, requiredNm),
+    violated: isGapViolated(gapNm, requiredNm),
+    gapSec: gapToTimeSec(gapNm, pair.followerKts),
+  }
+}
diff --git a/shared/utils/aiTraffic/sim.ts b/shared/utils/aiTraffic/sim.ts
new file mode 100644
index 0000000..49bf2dc
--- /dev/null
+++ b/shared/utils/aiTraffic/sim.ts
@@ -0,0 +1,213 @@
+/**
+ * The traffic simulation itself: spawning aircraft and advancing them on a 1 Hz
+ * tick (architecture design § 2).
+ *
+ * Deliberately 1-dimensional — distance along the route, altitude, speed. There
+ * is no 2D radar picture because nothing needs one: positions only ever surface
+ * in phraseology ("six miles final") and in the in-trail gap. A vector is booked
+ * as time on the timeline rather than flown as a turn — acoustically identical,
+ * an order of magnitude less code.
+ */
+
+import type { Rng } from './rng'
+import type { GeneratedCallsign } from './callsign'
+import { pilotVoiceFor } from '../voicePool'
+import type { SimAircraft, SimPhase } from './types'
+
+/** How fast IAS follows an assigned speed — roughly what a jet actually does. */
+export const SPEED_DRIFT_KTS_PER_SEC = 1
+
+/** Distance-to-field at which an arrival is handed from approach to tower. */
+export const FINAL_HANDOVER_NM = 8
+
+/** Where arrivals enter the picture. */
+export const SPAWN_DISTANCE_MIN_NM = 25
+export const SPAWN_DISTANCE_MAX_NM = 60
+
+/** How much of the remaining route one fix represents. */
+export const NM_PER_FIX = 8
+
+const FIX_CONSONANTS = 'BCDFGKLMNPRSTVXZ'
+const FIX_VOWELS = 'AEIOU'
+
+/**
+ * A small pool of invented but plausible-sounding 5-letter fixes per airport.
+ * v1 does not load real procedure data — directs here are ear realism, not
+ * navigation, and real SID/STAR fixes would be their own data project.
+ */
+export function generateFixPool(rng: Rng, count = 8): string[] {
+  const fixes = new Set<string>()
+  // Bounded so a pathological RNG can't spin here; the pool just ends up smaller.
+  for (let attempt = 0; attempt < count * 10 && fixes.size < count; attempt++) {
+    let name = ''
+    for (let i = 0; i < 5; i++) {
+      name += i % 2 === 0 ? rng.pick(FIX_CONSONANTS.split('')) : rng.pick(FIX_VOWELS.split(''))
+    }
+    fixes.add(name)
+  }
+  return [...fixes]
+}
+
+export type SpawnKind = 'arrival' | 'departure'
+
+export interface SpawnOptions {
+  rng: Rng
+  nowSec: number
+  frequency: string
+  fixPool: readonly string[]
+}
+
+/** Arrivals start out on the STAR; departures start at the holding point. */
+export function createSimAircraft(
+  generated: GeneratedCallsign,
+  kind: SpawnKind,
+  opts: SpawnOptions,
+): SimAircraft {
+  const { rng, nowSec, frequency, fixPool } = opts
+  const { callsign, callsignSpoken, type } = generated
+
+  const routeFixCount = Math.min(fixPool.length, rng.int(2, 4))
+  const routeFixes = Array.from({ length: routeFixCount }, () => rng.pick(fixPool))
+
+  if (kind === 'departure') {
+    return {
+      callsign,
+      callsignSpoken,
+      type,
+      voiceId: pilotVoiceFor(callsign),
+      phase: 'taxi_out',
+      frequency,
+      routeFixes,
+      distanceToFieldNm: 0,
+      altitudeFt: 0,
+      iasKts: 0,
+      assignedSpeedKts: null,
+      vectorDelaySec: 0,
+      runwaySlot: null,
+      nextEventAtSec: nowSec + rng.int(20, 60),
+      quietUntilSec: 0,
+    }
+  }
+
+  const distance = rng.float(SPAWN_DISTANCE_MIN_NM, SPAWN_DISTANCE_MAX_NM)
+  return {
+    callsign,
+    callsignSpoken,
+    type,
+    voiceId: pilotVoiceFor(callsign),
+    phase: 'inbound',
+    frequency,
+    routeFixes,
+    distanceToFieldNm: distance,
+    altitudeFt: rng.int(7, 12) * 1000,
+    // Inbound and already speed-limited below 10,000 ft.
+    iasKts: Math.max(type.approachKts, Math.min(250, type.cruiseKts * 0.55)),
+    assignedSpeedKts: null,
+    vectorDelaySec: 0,
+    runwaySlot: null,
+    nextEventAtSec: nowSec + rng.int(15, 45),
+    quietUntilSec: 0,
+  }
+}
+
+/** The linear phase order per flight kind. */
+const ARRIVAL_PHASES: readonly SimPhase[] = ['inbound', 'approach', 'final', 'rollout', 'handed_off']
+const DEPARTURE_PHASES: readonly SimPhase[] = ['taxi_out', 'lineup', 'takeoff', 'climbout', 'handed_off']
+
+export function nextPhase(phase: SimPhase): SimPhase {
+  const chain = ARRIVAL_PHASES.includes(phase) ? ARRIVAL_PHASES : DEPARTURE_PHASES
+  const index = chain.indexOf(phase)
+  if (index < 0 || index >= chain.length - 1) return 'handed_off'
+  return chain[index + 1]!
+}
+
+export function isArrival(aircraft: Pick<SimAircraft, 'phase'>): boolean {
+  return ARRIVAL_PHASES.includes(aircraft.phase)
+}
+
+/** Aircraft that have left the sector — the spawner reclaims their callsigns. */
+export function isDespawnable(aircraft: Pick<SimAircraft, 'phase'>): boolean {
+  return aircraft.phase === 'handed_off'
+}
+
+/**
+ * One tick of 1D kinematics. Mutates in place — the pool owns these objects and
+ * a tick runs every second, so copying them buys nothing.
+ */
+export function advanceAircraft(aircraft: SimAircraft, dtSec: number): void {
+  if (dtSec <= 0) return
+
+  // A vector is time, not geometry: while it burns down the aircraft holds its
+  // distance to the field instead of closing.
+  if (aircraft.vectorDelaySec > 0) {
+    aircraft.vectorDelaySec = Math.max(0, aircraft.vectorDelaySec - dtSec)
+    return
+  }
+
+  // IAS chases the assigned speed at ~1 kt/s, so later phraseology
+  // ("12 miles, speed 180") stays consistent with the model.
+  if (aircraft.assignedSpeedKts !== null) {
+    const delta = aircraft.assignedSpeedKts - aircraft.iasKts
+    const step = Math.min(Math.abs(delta), SPEED_DRIFT_KTS_PER_SEC * dtSec)
+    aircraft.iasKts += Math.sign(delta) * step
+  }
+
+  switch (aircraft.phase) {
+    case 'inbound':
+    case 'approach':
+    case 'final':
+      aircraft.distanceToFieldNm = Math.max(0, aircraft.distanceToFieldNm - (aircraft.iasKts * dtSec) / 3600)
+      aircraft.altitudeFt = Math.max(0, aircraft.altitudeFt - (aircraft.type.descentFpm * dtSec) / 60)
+      break
+    case 'takeoff':
+    case 'climbout':
+      aircraft.distanceToFieldNm += (aircraft.iasKts * dtSec) / 3600
+      aircraft.altitudeFt += (aircraft.type.climbFpm * dtSec) / 60
+      break
+    case 'rollout':
+      aircraft.iasKts = Math.max(0, aircraft.iasKts - 5 * dtSec)
+      break
+    default:
+      break
+  }
+}
+
+/** Move an aircraft to its next phase and schedule the following event. */
+export function advancePhase(aircraft: SimAircraft, rng: Rng, nowSec: number): void {
+  aircraft.phase = nextPhase(aircraft.phase)
+  switch (aircraft.phase) {
+    case 'takeoff':
+      aircraft.iasKts = aircraft.type.approachKts + 20
+      aircraft.nextEventAtSec = nowSec + rng.int(30, 60)
+      break
+    case 'climbout':
+      aircraft.assignedSpeedKts = null
+      aircraft.nextEventAtSec = nowSec + rng.int(60, 120)
+      break
+    case 'final':
+      aircraft.assignedSpeedKts = aircraft.type.approachKts
+      aircraft.nextEventAtSec = nowSec + rng.int(60, 120)
+      break
+    case 'handed_off':
+      aircraft.nextEventAtSec = Number.POSITIVE_INFINITY
+      break
+    default:
+      aircraft.nextEventAtSec = nowSec + rng.int(45, 90)
+      break
+  }
+}
+
+/**
+ * The aircraft immediately ahead of `follower` on the same approach: the closest
+ * one that is nearer to the field. Returns null when the follower is leading.
+ */
+export function findLeader(follower: SimAircraft, pool: readonly SimAircraft[]): SimAircraft | null {
+  let leader: SimAircraft | null = null
+  for (const other of pool) {
+    if (other === follower || other.callsign === follower.callsign) continue
+    if (!isArrival(other)) continue
+    if (other.distanceToFieldNm >= follower.distanceToFieldNm) continue
+    if (!leader || other.distanceToFieldNm > leader.distanceToFieldNm) leader = other
+  }
+  return leader
+}
diff --git a/shared/utils/aiTraffic/types.ts b/shared/utils/aiTraffic/types.ts
new file mode 100644
index 0000000..94403fc
--- /dev/null
+++ b/shared/utils/aiTraffic/types.ts
@@ -0,0 +1,50 @@
+import type { SimAircraftType } from '../../data/simAircraftTypes'
+
+/**
+ * Where a simulated aircraft is in its (deliberately 1-dimensional) life:
+ * distance along a route, altitude and speed. No 2D radar picture — positions
+ * only ever surface in phraseology ("six miles final") and in the in-trail gap
+ * calculation, and that needs nothing more.
+ */
+export type SimPhase =
+  | 'inbound' | 'approach' | 'final' | 'rollout'
+  | 'taxi_out' | 'lineup' | 'takeoff' | 'climbout' | 'handed_off'
+
+/** Runway timeline reservation, in sim seconds. */
+export interface RunwaySlot {
+  fromSec: number
+  toSec: number
+}
+
+export interface SimAircraft {
+  /** ICAO callsign as written, e.g. 'DLH472' or 'D-EKLM'. */
+  callsign: string
+  /** Full radiotelephony form, e.g. 'Lufthansa four seven two heavy'. */
+  callsignSpoken: string
+  type: SimAircraftType
+  /** Stable across the session — hashed from the callsign, never persisted. */
+  voiceId: string
+
+  phase: SimPhase
+  /** The frequency this aircraft is currently on; it is only audible on the tuned one. */
+  frequency: string
+  /** Remaining route; [0] is the next waypoint. */
+  routeFixes: string[]
+  distanceToFieldNm: number
+  altitudeFt: number
+  iasKts: number
+  /** Last speed instruction issued, if any. */
+  assignedSpeedKts: number | null
+  /** Accumulated vectoring delay — a vector is booked as time, not flown geometrically. */
+  vectorDelaySec: number
+  runwaySlot: RunwaySlot | null
+  /** Sim time of this aircraft's next planned radio event. */
+  nextEventAtSec: number
+  /**
+   * No further instruction to this aircraft before this sim time. A controller
+   * issues a clearance and then lets it take effect; without this the planner
+   * re-derives the same unresolved condition every tick and nags the same
+   * aircraft once a second.
+   */
+  quietUntilSec: number
+}
diff --git a/shared/utils/communicationsEngine.ts b/shared/utils/communicationsEngine.ts
index 21b6f99..f34c5b8 100644
--- a/shared/utils/communicationsEngine.ts
+++ b/shared/utils/communicationsEngine.ts
@@ -97,6 +97,12 @@ export interface EngineLog {
     radioCheck?: boolean
     offSchema?: boolean
     flow?: string
+    /**
+     * Simulated background traffic (useAiTraffic), not part of the user's own
+     * exchange with ATC. Purely cosmetic — it lets the log tone these lines down
+     * so they read as scenery rather than as something to act on.
+     */
+    traffic?: boolean
 }
 
 interface FlowSnapshot {
@@ -1423,7 +1429,7 @@ export default function useCommunicationsEngine() {
         speaker: Role,
         message: string,
         stateId: string,
-        options: { frequency?: string; flow?: string; radioCheck?: boolean; offSchema?: boolean } = {},
+        options: { frequency?: string; flow?: string; radioCheck?: boolean; offSchema?: boolean; traffic?: boolean } = {},
     ) {
         const entry: EngineLog = {
             timestamp: new Date(),
@@ -1435,6 +1441,7 @@ export default function useCommunicationsEngine() {
             flow: options.flow ?? (activeFlowSlug.value || undefined),
             radioCheck: options.radioCheck,
             offSchema: options.offSchema,
+            traffic: options.traffic,
         }
         communicationLog.value.push(entry)
     }
diff --git a/shared/utils/voicePool.ts b/shared/utils/voicePool.ts
new file mode 100644
index 0000000..e4f1dad
--- /dev/null
+++ b/shared/utils/voicePool.ts
@@ -0,0 +1,68 @@
+/**
+ * The one voice pool for the whole product — shared infrastructure for both
+ * `ai-traffic` (a stable voice per simulated aircraft) and the `multi-voice`
+ * roadmap item (a rotating voice per ATC position). Two disjoint partitions, one
+ * assignment function; deliberately not two systems (architecture design § 7).
+ *
+ * Assignment is a pure hash of the callsign / position, so the same "DLH472"
+ * sounds the same all session — and across sessions — without persisting any
+ * assignment state anywhere.
+ */
+
+/** Voices for ATC positions. `alloy` is today's hard-coded controller voice. */
+export const CONTROLLER_VOICES: readonly string[] = ['alloy', 'echo', 'onyx', 'sage']
+
+/** Voices for simulated pilots' readbacks. Disjoint from CONTROLLER_VOICES. */
+export const PILOT_VOICES: readonly string[] = ['ash', 'ballad', 'coral', 'fable', 'nova', 'shimmer']
+
+/**
+ * Never hand these to a simulated pilot: `verse` already belongs to the user's
+ * own readback (`speakPilotReadback`), and the live controller voice must stay
+ * distinguishable from the traffic around it.
+ */
+export const RESERVED_VOICES: readonly string[] = ['verse', 'alloy']
+
+/** FNV-1a, 32-bit. Small, stable, and dependency-free — good enough to bucket strings. */
+export function fnv1a(input: string): number {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i)
+    // hash * 16777619, kept in 32-bit unsigned range without BigInt.
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+  return hash >>> 0
+}
+
+/**
+ * Pick a voice from `pool` for `key`, skipping anything in `reserved`.
+ * Walks forward from the hashed index so a collision with a reserved voice
+ * degrades to the next pool entry instead of failing.
+ */
+export function voiceFromPool(
+  key: string,
+  pool: readonly string[],
+  reserved: readonly string[] = RESERVED_VOICES,
+): string {
+  const usable = pool.filter(v => !reserved.includes(v))
+  const candidates = usable.length ? usable : pool
+  if (!candidates.length) throw new Error('voiceFromPool: empty voice pool')
+  return candidates[fnv1a(key) % candidates.length]!
+}
+
+/**
+ * The stable voice of a simulated aircraft. `reserved` lets a caller exclude the
+ * controller voice that is live right now (relevant once `multi-voice` rotates
+ * it), on top of the permanently reserved ones.
+ */
+export function pilotVoiceFor(callsign: string, reserved: readonly string[] = RESERVED_VOICES): string {
+  return voiceFromPool(callsign.toUpperCase(), PILOT_VOICES, reserved)
+}
+
+/**
+ * The voice of an ATC position (`multi-voice`). Traffic doesn't call this yet —
+ * it exists so the future feature reuses this pool rather than inventing a
+ * second assignment path.
+ */
+export function controllerVoiceFor(position: string): string {
+  return voiceFromPool(position.toUpperCase(), CONTROLLER_VOICES, [])
+}
diff --git a/tests/shared/aiTrafficCallsign.test.ts b/tests/shared/aiTrafficCallsign.test.ts
new file mode 100644
index 0000000..8165154
--- /dev/null
+++ b/tests/shared/aiTrafficCallsign.test.ts
@@ -0,0 +1,250 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { createRng, trafficSeed } from '~~/shared/utils/aiTraffic/rng'
+import {
+  TRAFFIC_AIRLINES,
+  VFR_REGISTRATION_POOL,
+  callsignPrefix,
+  callsignTail,
+  createCallsignFactory,
+  isCallsignDistinct,
+  levenshtein,
+  spokenCallsign,
+} from '~~/shared/utils/aiTraffic/callsign'
+import { findSimAircraftType } from '~~/shared/data/simAircraftTypes'
+
+describe('seeded rng', () => {
+  it('replays identically for the same seed', () => {
+    const a = createRng('seed-1')
+    const b = createRng('seed-1')
+    for (let i = 0; i < 50; i++) assert.equal(a.next(), b.next())
+  })
+
+  it('diverges for different seeds', () => {
+    const a = createRng('seed-1')
+    const b = createRng('seed-2')
+    const left = Array.from({ length: 20 }, () => a.next())
+    const right = Array.from({ length: 20 }, () => b.next())
+    assert.notDeepEqual(left, right)
+  })
+
+  it('stays inside its declared ranges', () => {
+    const rng = createRng('ranges')
+    for (let i = 0; i < 500; i++) {
+      const u = rng.next()
+      assert.ok(u >= 0 && u < 1)
+      const n = rng.int(3, 7)
+      assert.ok(Number.isInteger(n) && n >= 3 && n <= 7)
+      const f = rng.float(1, 2)
+      assert.ok(f >= 1 && f < 2)
+    }
+  })
+
+  it('hits both ends of an int range', () => {
+    const rng = createRng('ends')
+    const seen = new Set<number>()
+    for (let i = 0; i < 200; i++) seen.add(rng.int(0, 1))
+    assert.deepEqual([...seen].sort(), [0, 1])
+  })
+
+  it('respects weights', () => {
+    const rng = createRng('weights')
+    let heavy = 0
+    for (let i = 0; i < 1000; i++) {
+      if (rng.weighted([{ value: 'a', weight: 90 }, { value: 'b', weight: 10 }]) === 'a') heavy++
+    }
+    assert.ok(heavy > 850 && heavy < 950, `expected ~900 'a', got ${heavy}`)
+  })
+
+  it('never returns a zero-weight option', () => {
+    const rng = createRng('zero-weight')
+    for (let i = 0; i < 100; i++) {
+      assert.equal(rng.weighted([{ value: 'a', weight: 1 }, { value: 'b', weight: 0 }]), 'a')
+    }
+  })
+
+  it('rejects degenerate inputs instead of returning undefined', () => {
+    const rng = createRng('degenerate')
+    assert.throws(() => rng.pick([]), /empty list/)
+    assert.throws(() => rng.weighted([]), /no positive weights/)
+    assert.throws(() => rng.weighted([{ value: 'a', weight: 0 }]), /no positive weights/)
+  })
+
+  it('does not degenerate when the seed hashes to zero', () => {
+    const rng = createRng(0)
+    const values = Array.from({ length: 10 }, () => rng.next())
+    assert.equal(new Set(values).size, 10)
+  })
+
+  it('derives a per-session, per-day seed', () => {
+    const day = new Date(2026, 6, 16)
+    assert.equal(trafficSeed('abc', day), 'abc|2026-7-16')
+    assert.notEqual(trafficSeed('abc', day), trafficSeed('abc', new Date(2026, 6, 17)))
+    assert.notEqual(trafficSeed('abc', day), trafficSeed('abd', day))
+  })
+})
+
+describe('callsign decomposition', () => {
+  it('splits airline callsigns into designator and tail', () => {
+    assert.equal(callsignPrefix('DLH472'), 'DLH')
+    assert.equal(callsignTail('DLH472'), '472')
+    assert.equal(callsignPrefix('EZY93A'), 'EZY')
+    assert.equal(callsignTail('EZY93A'), '93A')
+  })
+
+  it('treats registrations as prefix-less', () => {
+    assert.equal(callsignPrefix('D-EMIL'), '')
+    assert.equal(callsignTail('D-EMIL'), 'EMIL')
+    assert.equal(callsignPrefix('N123AB'), '')
+    assert.equal(callsignTail('N123AB'), '123AB')
+  })
+})
+
+describe('levenshtein', () => {
+  it('measures the edits between spoken tails', () => {
+    assert.equal(levenshtein('39A', '39A'), 0)
+    assert.equal(levenshtein('39A', '39B'), 1)
+    assert.equal(levenshtein('39A', '47B'), 3)
+    assert.equal(levenshtein('', '472'), 3)
+    assert.equal(levenshtein('472', ''), 3)
+  })
+})
+
+describe('isCallsignDistinct — the three collision rules', () => {
+  it('rule 1: rejects the user callsign verbatim', () => {
+    assert.equal(isCallsignDistinct('DLH39A', ['DLH39A']), false)
+  })
+
+  it('rule 1: ignores casing and hyphens when comparing', () => {
+    assert.equal(isCallsignDistinct('d-emil', ['D-EMIL']), false)
+  })
+
+  it('rule 2: rejects any aircraft from the user airline', () => {
+    assert.equal(isCallsignDistinct('DLH8172', ['DLH39A']), false)
+  })
+
+  it('rule 3: rejects a confusable tail across airlines', () => {
+    // BAW39A vs DLH39A — different airline, identical spoken number.
+    assert.equal(isCallsignDistinct('BAW39A', ['DLH39A']), false)
+    // One digit apart is still one mishearing away.
+    assert.equal(isCallsignDistinct('BAW39B', ['DLH39A']), false)
+  })
+
+  it('rule 3: accepts a tail that differs in two positions', () => {
+    assert.equal(isCallsignDistinct('BAW47B', ['DLH39A']), true)
+  })
+
+  it('rule 3: guards VFR registrations too', () => {
+    assert.equal(isCallsignDistinct('D-EMIT', ['D-EMIL']), false)
+    assert.equal(isCallsignDistinct('D-EKLM', ['D-EMIL']), true)
+  })
+
+  it('rejects an empty candidate', () => {
+    assert.equal(isCallsignDistinct('', ['DLH39A']), false)
+  })
+
+  it('accepts anything when nothing is blocked', () => {
+    assert.equal(isCallsignDistinct('DLH472', []), true)
+  })
+})
+
+describe('spokenCallsign', () => {
+  it('renders the airline telephony name and per-digit number', () => {
+    // Digits come out in the product's ICAO spelling ("too", "tree", "niner").
+    const spoken = spokenCallsign('DLH472', findSimAircraftType('A320')!)
+    assert.match(spoken, /^Lufthansa four seven too$/i)
+  })
+
+  it('appends heavy for a widebody and super for the A380', () => {
+    assert.match(spokenCallsign('BAW118', findSimAircraftType('B77W')!), /heavy$/i)
+    assert.match(spokenCallsign('UAL900', findSimAircraftType('A388')!), /super$/i)
+  })
+
+  it('leaves a medium without a wake suffix', () => {
+    const spoken = spokenCallsign('EZY93', findSimAircraftType('A320')!)
+    assert.doesNotMatch(spoken, /heavy|super/i)
+  })
+})
+
+describe('createCallsignFactory', () => {
+  const userCallsigns = ['DLH39A', 'DLH39A']
+
+  it('never issues anything that collides with the user or with itself', () => {
+    // Fresh seeds, many draws: no run may ever produce a confusable callsign.
+    for (let seed = 0; seed < 40; seed++) {
+      const factory = createCallsignFactory({
+        rng: createRng(`factory-${seed}`),
+        tier: 'major',
+        userCallsigns,
+      })
+      const issued: string[] = []
+      for (let i = 0; i < 5; i++) {
+        const generated = factory.next()
+        assert.ok(generated, 'factory ran out of distinct callsigns')
+        assert.ok(
+          isCallsignDistinct(generated.callsign, [...userCallsigns, ...issued]),
+          `${generated.callsign} collides (issued: ${issued.join(', ')})`,
+        )
+        issued.push(generated.callsign)
+      }
+    }
+  })
+
+  it('never issues a callsign from the user airline', () => {
+    const factory = createCallsignFactory({ rng: createRng('airline'), tier: 'major', userCallsigns })
+    for (let i = 0; i < 5; i++) {
+      assert.notEqual(callsignPrefix(factory.next()!.callsign), 'DLH')
+    }
+  })
+
+  it('never issues a registration from the VFR pool the user may be flying', () => {
+    const factory = createCallsignFactory({ rng: createRng('vfr'), tier: 'ga', userCallsigns: ['D-EMIL'] })
+    for (let i = 0; i < 5; i++) {
+      const cs = factory.next()!.callsign
+      assert.equal(VFR_REGISTRATION_POOL.includes(cs), false, `${cs} is in the VFR pool`)
+    }
+  })
+
+  it('only uses airline designators the radiotelephony normalizer can speak', () => {
+    const factory = createCallsignFactory({ rng: createRng('speakable'), tier: 'major', userCallsigns })
+    for (let i = 0; i < 5; i++) {
+      const prefix = callsignPrefix(factory.next()!.callsign)
+      if (prefix) assert.ok(TRAFFIC_AIRLINES.includes(prefix), `${prefix} has no telephony name`)
+    }
+  })
+
+  it('is deterministic for a given seed', () => {
+    const draw = () => {
+      const factory = createCallsignFactory({ rng: createRng('fixed'), tier: 'major', userCallsigns })
+      return [factory.next(), factory.next(), factory.next()].map(g => `${g!.callsign}/${g!.type.icao}`)
+    }
+    assert.deepEqual(draw(), draw())
+  })
+
+  it('weights the type mix by tier', () => {
+    const classesFor = (tier: 'major' | 'ga') => {
+      const factory = createCallsignFactory({ rng: createRng(`mix-${tier}`), tier, userCallsigns })
+      // Release each draw so the collision rules don't exhaust the pool.
+      return Array.from({ length: 200 }, () => {
+        const g = factory.next()
+        if (g) factory.release(g.callsign)
+        return g?.type.class
+      }).filter(Boolean)
+    }
+    const major = classesFor('major')
+    const ga = classesFor('ga')
+    assert.ok(major.filter(c => c === 'narrowbody').length > major.length * 0.5, 'major should be narrowbody-heavy')
+    assert.equal(major.filter(c => c === 'ga').length, 0, 'major must not spawn GA singles')
+    assert.ok(ga.filter(c => c === 'ga').length > ga.length * 0.6, 'ga field should be GA-heavy')
+    assert.equal(ga.filter(c => c === 'widebody').length, 0, 'a GA field must not spawn widebodies')
+  })
+
+  it('frees a callsign again on release', () => {
+    const factory = createCallsignFactory({ rng: createRng('release'), tier: 'major', userCallsigns })
+    const first = factory.next()!
+    assert.deepEqual(factory.issued(), [first.callsign])
+    factory.release(first.callsign)
+    assert.deepEqual(factory.issued(), [])
+  })
+})
diff --git a/tests/shared/aiTrafficGating.test.ts b/tests/shared/aiTrafficGating.test.ts
new file mode 100644
index 0000000..d22224b
--- /dev/null
+++ b/tests/shared/aiTrafficGating.test.ts
@@ -0,0 +1,205 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  DEFAULT_READBACK_PROTECTION_MS,
+  evaluateGate,
+  gateOpen,
+  readbackPending,
+  type GateInput,
+} from '~~/shared/utils/aiTraffic/gating'
+
+const NOW = 1_000_000
+
+/** A session in its natural resting state: open frequency, nothing pending. */
+const openInput = (overrides: Partial<GateInput> = {}): GateInput => ({
+  aiTrafficEnabled: true,
+  isRecording: false,
+  transmitInFlight: false,
+  sessionActive: true,
+  readback: {
+    currentStateRole: 'atc',
+    backendExpectedPhrase: null,
+    lastControllerSpeechAtMs: null,
+    nowMs: NOW,
+  },
+  ...overrides,
+})
+
+describe('readbackPending — the fresh-readback window', () => {
+  const freshWindow = {
+    currentStateRole: 'pilot' as const,
+    backendExpectedPhrase: 'Cleared to land runway 25R, DLH39A',
+    lastControllerSpeechAtMs: NOW,
+    nowMs: NOW + 1000,
+  }
+
+  it('locks the frequency right after ATC issues an instruction', () => {
+    assert.equal(readbackPending(freshWindow), true)
+  })
+
+  it('stays locked for the whole protection window', () => {
+    assert.equal(
+      readbackPending({ ...freshWindow, nowMs: NOW + DEFAULT_READBACK_PROTECTION_MS - 1 }),
+      true,
+    )
+  })
+
+  it('releases once the window lapses — a dawdling pilot must not mute the frequency forever', () => {
+    assert.equal(
+      readbackPending({ ...freshWindow, nowMs: NOW + DEFAULT_READBACK_PROTECTION_MS }),
+      false,
+    )
+    assert.equal(readbackPending({ ...freshWindow, nowMs: NOW + 60_000 }), false)
+  })
+
+  it('does not lock on an ATC or system state, even with a phrase set', () => {
+    assert.equal(readbackPending({ ...freshWindow, currentStateRole: 'atc' }), false)
+    assert.equal(readbackPending({ ...freshWindow, currentStateRole: 'system' }), false)
+    assert.equal(readbackPending({ ...freshWindow, currentStateRole: undefined }), false)
+  })
+
+  it('does not lock on a pilot state the backend expects nothing for', () => {
+    assert.equal(readbackPending({ ...freshWindow, backendExpectedPhrase: null }), false)
+    assert.equal(readbackPending({ ...freshWindow, backendExpectedPhrase: '' }), false)
+  })
+
+  it('does not lock before any ATC instruction has been spoken', () => {
+    assert.equal(readbackPending({ ...freshWindow, lastControllerSpeechAtMs: null }), false)
+  })
+
+  it('supports the literal-strict reading via one parameter, not a second code path', () => {
+    const strict = { ...freshWindow, nowMs: NOW + 3_600_000, readbackProtectionMs: Number.POSITIVE_INFINITY }
+    assert.equal(readbackPending(strict), true)
+  })
+
+  it('supports a custom finite window', () => {
+    const win = { ...freshWindow, readbackProtectionMs: 5000 }
+    assert.equal(readbackPending({ ...win, nowMs: NOW + 4999 }), true)
+    assert.equal(readbackPending({ ...win, nowMs: NOW + 5000 }), false)
+  })
+})
+
+describe('evaluateGate — the chain', () => {
+  it('opens on a quiet, active session', () => {
+    assert.deepEqual(evaluateGate(openInput()), { open: true })
+    assert.equal(gateOpen(openInput()), true)
+  })
+
+  it('is shut while the settings toggle is off', () => {
+    assert.deepEqual(evaluateGate(openInput({ aiTrafficEnabled: false })), {
+      open: false,
+      reason: 'disabled',
+    })
+  })
+
+  it('is shut while the user holds PTT — absolutely, no window', () => {
+    assert.deepEqual(evaluateGate(openInput({ isRecording: true })), {
+      open: false,
+      reason: 'recording',
+    })
+  })
+
+  it('is shut while a user transmission awaits the backend', () => {
+    assert.deepEqual(evaluateGate(openInput({ transmitInFlight: true })), {
+      open: false,
+      reason: 'transmit_in_flight',
+    })
+  })
+
+  it('is shut without an active session', () => {
+    assert.deepEqual(evaluateGate(openInput({ sessionActive: false })), {
+      open: false,
+      reason: 'session_inactive',
+    })
+  })
+
+  it('is shut inside the fresh readback window', () => {
+    const input = openInput({
+      readback: {
+        currentStateRole: 'pilot',
+        backendExpectedPhrase: 'Runway 25R, cleared to land, DLH39A',
+        lastControllerSpeechAtMs: NOW,
+        nowMs: NOW + 2000,
+      },
+    })
+    assert.deepEqual(evaluateGate(input), { open: false, reason: 'readback_pending' })
+  })
+
+  it('reopens after the readback window lapses', () => {
+    const input = openInput({
+      readback: {
+        currentStateRole: 'pilot',
+        backendExpectedPhrase: 'Runway 25R, cleared to land, DLH39A',
+        lastControllerSpeechAtMs: NOW,
+        nowMs: NOW + DEFAULT_READBACK_PROTECTION_MS + 1,
+      },
+    })
+    assert.equal(gateOpen(input), true)
+  })
+
+  it('reports the most specific reason when several block at once', () => {
+    const everythingShut = openInput({
+      aiTrafficEnabled: false,
+      isRecording: true,
+      transmitInFlight: true,
+      sessionActive: false,
+    })
+    assert.equal(evaluateGate(everythingShut).reason, 'disabled')
+    assert.equal(evaluateGate({ ...everythingShut, aiTrafficEnabled: true }).reason, 'recording')
+    assert.equal(
+      evaluateGate({ ...everythingShut, aiTrafficEnabled: true, isRecording: false }).reason,
+      'transmit_in_flight',
+    )
+  })
+
+  it('PTT outranks the readback window: the user speaking is never negotiable', () => {
+    const input = openInput({
+      isRecording: true,
+      readback: {
+        currentStateRole: 'pilot',
+        backendExpectedPhrase: 'anything',
+        lastControllerSpeechAtMs: NOW - 60_000, // window long lapsed
+        nowMs: NOW,
+      },
+    })
+    assert.equal(gateOpen(input), false)
+  })
+})
+
+describe('evaluateGate — the two evaluation points', () => {
+  // The chain is called before enqueuing AND again when the task starts playing.
+  // Seconds pass in between; these are the cases that must differ across them.
+  it('a gate that was open at enqueue time is shut at play time once PTT goes down', () => {
+    const atEnqueue = openInput()
+    assert.equal(gateOpen(atEnqueue), true)
+    const atPlayback = { ...atEnqueue, isRecording: true }
+    assert.equal(gateOpen(atPlayback), false)
+  })
+
+  it('a gate that was open at enqueue time is shut at play time once the toggle flips off', () => {
+    // This is what makes "finish the current call, start nothing new" work
+    // without touching the speech queue's mechanics.
+    assert.equal(gateOpen(openInput()), true)
+    assert.equal(gateOpen(openInput({ aiTrafficEnabled: false })), false)
+  })
+
+  it('a gate that was open at enqueue time is shut at play time once ATC issues an instruction', () => {
+    assert.equal(gateOpen(openInput()), true)
+    const afterAtcSpoke = openInput({
+      readback: {
+        currentStateRole: 'pilot',
+        backendExpectedPhrase: 'Descend 4000 feet, DLH39A',
+        lastControllerSpeechAtMs: NOW + 500,
+        nowMs: NOW + 900,
+      },
+    })
+    assert.equal(gateOpen(afterAtcSpoke), false)
+  })
+
+  it('a gate that was shut at enqueue time can be open at play time', () => {
+    const duringPtt = openInput({ isRecording: true })
+    assert.equal(gateOpen(duringPtt), false)
+    assert.equal(gateOpen({ ...duringPtt, isRecording: false }), true)
+  })
+})
diff --git a/tests/shared/aiTrafficInstructions.test.ts b/tests/shared/aiTrafficInstructions.test.ts
new file mode 100644
index 0000000..b10bc06
--- /dev/null
+++ b/tests/shared/aiTrafficInstructions.test.ts
@@ -0,0 +1,424 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { createRng } from '~~/shared/utils/aiTraffic/rng'
+import { findSimAircraftType } from '~~/shared/data/simAircraftTypes'
+import {
+  SPEED_LADDER,
+  applyDirect,
+  isAtMinimumSpeed,
+  nextSpeedStep,
+  planInstruction,
+  renderInstruction,
+  speedLadderFor,
+  validateDirect,
+  type PlannerContext,
+} from '~~/shared/utils/aiTraffic/instructions'
+import type { SimAircraft, SimPhase } from '~~/shared/utils/aiTraffic/types'
+
+const A320 = findSimAircraftType('A320')!   // Medium, Vref 130
+const B77W = findSimAircraftType('B77W')!   // Heavy, Vref 145
+const C172 = findSimAircraftType('C172')!   // Light
+
+function aircraft(overrides: Partial<SimAircraft> = {}): SimAircraft {
+  return {
+    callsign: 'BAW118',
+    callsignSpoken: 'Speedbird one one eight',
+    type: A320,
+    voiceId: 'nova',
+    phase: 'approach',
+    frequency: '119.000',
+    routeFixes: ['KOTAP', 'RIVAK', 'DOMUX'],
+    distanceToFieldNm: 20,
+    altitudeFt: 6000,
+    iasKts: 250,
+    assignedSpeedKts: null,
+    vectorDelaySec: 0,
+    runwaySlot: null,
+    nextEventAtSec: Number.POSITIVE_INFINITY,
+    quietUntilSec: 0,
+    ...overrides,
+  }
+}
+
+describe('nextSpeedStep — the ladder', () => {
+  it('steps down one rung at a time, ending on the type approach speed', () => {
+    let ac = aircraft({ iasKts: 250, assignedSpeedKts: null })
+    const issued: number[] = []
+    for (let i = 0; i < 10; i++) {
+      const step = nextSpeedStep(ac)
+      if (step === null) break
+      issued.push(step)
+      ac = { ...ac, assignedSpeedKts: step }
+    }
+    assert.deepEqual(issued, [220, 210, 190, 180, 170, 160, A320.approachKts])
+  })
+
+  it('drops rungs that sit below a slower type approach speed', () => {
+    // B744 rotates at Vref 150 — the 160 rung is its last fixed one, then 150.
+    assert.deepEqual(speedLadderFor(findSimAircraftType('B744')!), [250, 220, 210, 190, 180, 170, 160, 150])
+    // A hypothetical fast-approaching type never sees the low rungs at all.
+    assert.deepEqual(speedLadderFor({ ...A320, approachKts: 185 }), [250, 220, 210, 190, 185])
+  })
+
+  it('never assigns above 250 kt below 10,000 ft', () => {
+    const fast = aircraft({ altitudeFt: 8000, iasKts: 300, assignedSpeedKts: null })
+    const step = nextSpeedStep(fast)!
+    assert.ok(step <= 250, `assigned ${step} below 10,000 ft`)
+    assert.equal(step, 250)
+  })
+
+  it('may assign above 250 kt above 10,000 ft', () => {
+    const high = aircraft({ altitudeFt: 14000, iasKts: 300, assignedSpeedKts: null })
+    assert.equal(nextSpeedStep(high), 250)
+  })
+
+  it('bottoms out at the type Vref and has nothing left to say below it', () => {
+    // A320 Vref 130: 160 → 130, and 130 is the end of the road.
+    assert.equal(nextSpeedStep(aircraft({ assignedSpeedKts: 160 })), 130)
+    assert.equal(nextSpeedStep(aircraft({ assignedSpeedKts: 130 })), null)
+    // B77W Vref 145 — its floor is higher than the A320's, as it must be.
+    assert.equal(nextSpeedStep(aircraft({ type: B77W, assignedSpeedKts: 160 })), 145)
+    assert.equal(nextSpeedStep(aircraft({ type: B77W, assignedSpeedKts: 145 })), null)
+  })
+
+  it('never assigns below Vref for any type, from any rung', () => {
+    for (const type of [A320, B77W, findSimAircraftType('E190')!, findSimAircraftType('A388')!, findSimAircraftType('B744')!]) {
+      for (const rung of [...SPEED_LADDER, type.approachKts]) {
+        const step = nextSpeedStep(aircraft({ type, assignedSpeedKts: rung + 1 }))
+        if (step !== null) assert.ok(step >= type.approachKts, `${type.icao}: ${step} < Vref ${type.approachKts}`)
+      }
+    }
+  })
+
+  it('gives a Cessna no jet speed callout at all', () => {
+    assert.equal(nextSpeedStep(aircraft({ type: C172, iasKts: 110 })), null)
+    assert.equal(isAtMinimumSpeed(aircraft({ type: C172 })), true)
+  })
+
+  it('only controls speed in phases where it makes sense', () => {
+    const controllable: SimPhase[] = ['inbound', 'approach']
+    const nonsense: SimPhase[] = ['final', 'rollout', 'taxi_out', 'lineup', 'takeoff', 'climbout', 'handed_off']
+    for (const phase of controllable) {
+      assert.notEqual(nextSpeedStep(aircraft({ phase })), null, `${phase} should allow speed control`)
+    }
+    for (const phase of nonsense) {
+      assert.equal(nextSpeedStep(aircraft({ phase })), null, `${phase} must not get an approach reduction`)
+    }
+  })
+
+  it('measures from the assigned speed, not the current one, while IAS is still catching up', () => {
+    // Told 220, still decelerating through 240 — the next rung is 210, not 220 again.
+    assert.equal(nextSpeedStep(aircraft({ iasKts: 240, assignedSpeedKts: 220 })), 210)
+  })
+})
+
+describe('validateDirect', () => {
+  const ctx = { gapNm: 30, requiredNm: 5, nmPerFix: 8 }
+
+  it('accepts a fix that lies ahead with plenty of air', () => {
+    const result = validateDirect(aircraft(), 'DOMUX', ctx)
+    assert.equal(result.valid, true)
+    assert.equal(result.fixIndex, 2)
+    assert.equal(result.savedNm, 16)
+  })
+
+  it('rejects the fix the aircraft is already proceeding to', () => {
+    assert.deepEqual(validateDirect(aircraft(), 'KOTAP', ctx), { valid: false, reason: 'behind' })
+  })
+
+  it('rejects a fix that is not on the remaining route', () => {
+    assert.deepEqual(validateDirect(aircraft(), 'NOWAY', ctx), { valid: false, reason: 'not_on_route' })
+  })
+
+  it('rejects a direct without the headroom that makes it a reward, not a fix', () => {
+    const result = validateDirect(aircraft(), 'DOMUX', { ...ctx, gapNm: 9 })
+    assert.deepEqual(result, { valid: false, reason: 'no_headroom' })
+  })
+
+  it('rejects a shortcut that would bust the minimum the moment it is read back', () => {
+    // 20 NM gap clears the 2× headroom, but cutting 16 NM leaves only 4 < 5 required.
+    const result = validateDirect(aircraft(), 'DOMUX', { ...ctx, gapNm: 20 })
+    assert.deepEqual(result, { valid: false, reason: 'gap_conflict' })
+  })
+
+  it('is never generated outside the phases where a shortcut means anything', () => {
+    for (const phase of ['final', 'climbout', 'taxi_out', 'rollout'] as SimPhase[]) {
+      assert.deepEqual(validateDirect(aircraft({ phase }), 'DOMUX', ctx), { valid: false, reason: 'wrong_phase' })
+    }
+  })
+})
+
+describe('applyDirect', () => {
+  it('shortens the route and the distance together, so later phraseology stays consistent', () => {
+    const ac = aircraft({ distanceToFieldNm: 40 })
+    const validation = validateDirect(ac, 'DOMUX', { gapNm: 60, requiredNm: 5, nmPerFix: 8 })
+    applyDirect(ac, validation)
+    assert.deepEqual(ac.routeFixes, ['DOMUX'])
+    assert.equal(ac.distanceToFieldNm, 24)
+  })
+
+  it('ignores an invalid direct rather than corrupting the route', () => {
+    const ac = aircraft()
+    applyDirect(ac, { valid: false, reason: 'behind' })
+    assert.deepEqual(ac.routeFixes, ['KOTAP', 'RIVAK', 'DOMUX'])
+    assert.equal(ac.distanceToFieldNm, 20)
+  })
+
+  it('never drives the distance to the field negative', () => {
+    const ac = aircraft({ distanceToFieldNm: 4 })
+    applyDirect(ac, { valid: true, fixIndex: 2, fix: 'DOMUX', savedNm: 16 })
+    assert.equal(ac.distanceToFieldNm, 0)
+  })
+})
+
+describe('planInstruction — the decision table', () => {
+  const baseCtx = (overrides: Partial<PlannerContext> = {}): PlannerContext => ({
+    nowSec: 1000,
+    rng: createRng('planner'),
+    leader: null,
+    occupiedSlots: [],
+    lastDeparture: null,
+    handover: null,
+    nmPerFix: 8,
+    silentForSec: 0,
+    ambientAfterSec: 60,
+    ...overrides,
+  })
+
+  it('row 7: a sector boundary hands the aircraft off', () => {
+    const plan = planInstruction(
+      aircraft({ nextEventAtSec: 900 }),
+      baseCtx({ handover: { station: 'Frankfurt Tower', frequency: '119.900' } }),
+    )
+    assert.equal(plan?.kind, 'handover')
+    assert.equal(plan?.handoverFrequency, '119.900')
+  })
+
+  it('row 3: a departure behind a heavy is held for the wake timer', () => {
+    const plan = planInstruction(
+      aircraft({ phase: 'lineup', nextEventAtSec: 900 }),
+      baseCtx({ lastDeparture: { type: B77W, atSec: 950 } }),
+    )
+    assert.equal(plan?.kind, 'wake_hold')
+    assert.equal(plan?.holdSec, 130) // 180 required − 50 elapsed
+  })
+
+  it('row 3: no hold once the wake timer has run out', () => {
+    const plan = planInstruction(
+      aircraft({ phase: 'lineup', nextEventAtSec: 900 }),
+      baseCtx({ lastDeparture: { type: B77W, atSec: 800 } }),
+    )
+    assert.notEqual(plan?.kind, 'wake_hold')
+  })
+
+  it('row 3: no hold behind a medium — runway occupancy covers that', () => {
+    const plan = planInstruction(
+      aircraft({ phase: 'lineup', nextEventAtSec: 900 }),
+      baseCtx({ lastDeparture: { type: A320, atSec: 995 } }),
+    )
+    assert.notEqual(plan?.kind, 'wake_hold')
+  })
+
+  it('row 2: simulated traffic yields to the user runway reservation', () => {
+    const plan = planInstruction(
+      aircraft({ phase: 'final', runwaySlot: { fromSec: 1000, toSec: 1060 }, nextEventAtSec: 900 }),
+      baseCtx({ occupiedSlots: [{ fromSec: 1030, toSec: 1120 }] }),
+    )
+    assert.equal(plan?.kind, 'slot_hold')
+  })
+
+  it('row 2: a free slot does not trigger a hold', () => {
+    const plan = planInstruction(
+      aircraft({ phase: 'final', runwaySlot: { fromSec: 1000, toSec: 1060 } }),
+      baseCtx({ occupiedSlots: [{ fromSec: 1200, toSec: 1260 }] }),
+    )
+    assert.notEqual(plan?.kind, 'slot_hold')
+  })
+
+  it('row 2: an aircraft does not conflict with its own reservation', () => {
+    // The caller passes the whole runway timeline, own slot included. Counting it
+    // would hold every aircraft against itself forever instead of ever flying.
+    const slot = { fromSec: 1000, toSec: 1060 }
+    const plan = planInstruction(
+      aircraft({ phase: 'final', runwaySlot: slot }),
+      baseCtx({ occupiedSlots: [slot] }),
+    )
+    assert.notEqual(plan?.kind, 'slot_hold')
+  })
+
+  it('row 1: a due phase change produces a phase call', () => {
+    const plan = planInstruction(aircraft({ nextEventAtSec: 999 }), baseCtx())
+    assert.equal(plan?.kind, 'phase')
+  })
+
+  it('row 4: closing up with speed left produces one step down', () => {
+    const plan = planInstruction(
+      aircraft({ distanceToFieldNm: 15.5, iasKts: 250 }),
+      baseCtx({ leader: { distanceToFieldNm: 10, type: B77W } }), // required 5, gap 5.5
+    )
+    assert.equal(plan?.kind, 'speed')
+    assert.equal(plan?.speedKts, 220)
+  })
+
+  it('row 5: a busted minimum at minimum speed produces a vector', () => {
+    // Already told to fly its Vref — speed control has nothing left to give.
+    const plan = planInstruction(
+      aircraft({ distanceToFieldNm: 14, iasKts: 130, assignedSpeedKts: A320.approachKts }),
+      baseCtx({ leader: { distanceToFieldNm: 10, type: B77W } }), // required 5, gap 4
+    )
+    assert.equal(plan?.kind, 'vector')
+    assert.ok(plan!.headingDeg! >= 10 && plan!.headingDeg! <= 360)
+    assert.ok(plan!.vectorDelaySec! >= 60 && plan!.vectorDelaySec! <= 120)
+  })
+
+  it('row 5: prefers speed over a vector while a rung remains', () => {
+    const plan = planInstruction(
+      aircraft({ distanceToFieldNm: 14, iasKts: 250 }),
+      baseCtx({ leader: { distanceToFieldNm: 10, type: B77W } }),
+    )
+    assert.equal(plan?.kind, 'speed', 'a vector is the last resort, not the first')
+  })
+
+  it('row 5: a GA aircraft with no ladder left goes straight to a vector', () => {
+    const plan = planInstruction(
+      aircraft({ type: C172, distanceToFieldNm: 12, iasKts: 90 }),
+      baseCtx({ leader: { distanceToFieldNm: 10, type: B77W } }),
+    )
+    assert.equal(plan?.kind, 'vector')
+  })
+
+  it('row 6: a direct only shows up with a lot of air, and only rarely', () => {
+    const kinds = Array.from({ length: 400 }, (_, i) =>
+      planInstruction(
+        aircraft({ distanceToFieldNm: 60 }),
+        baseCtx({ rng: createRng(`direct-${i}`), leader: { distanceToFieldNm: 10, type: A320 } }),
+      )?.kind,
+    )
+    const directs = kinds.filter(k => k === 'direct').length
+    assert.ok(directs > 0, 'a direct should occasionally fire on a quiet picture')
+    assert.ok(directs < 100, `a direct should stay rare, fired ${directs}/400`)
+  })
+
+  it('row 6: never issues a direct when the picture is tight', () => {
+    for (let i = 0; i < 200; i++) {
+      const plan = planInstruction(
+        aircraft({ distanceToFieldNm: 14, iasKts: 130, assignedSpeedKts: A320.approachKts }),
+        baseCtx({ rng: createRng(`tight-${i}`), leader: { distanceToFieldNm: 10, type: B77W } }),
+      )
+      assert.notEqual(plan?.kind, 'direct')
+    }
+  })
+
+  it('row 8: a long-silent frequency gets ambient chatter', () => {
+    const plan = planInstruction(aircraft(), baseCtx({ silentForSec: 75, ambientAfterSec: 60 }))
+    assert.equal(plan?.kind, 'ambient')
+  })
+
+  it('row 8: no ambient chatter while the frequency is still busy', () => {
+    const plan = planInstruction(aircraft(), baseCtx({ silentForSec: 20, ambientAfterSec: 60 }))
+    assert.equal(plan, null)
+  })
+
+  it('says nothing at all when no row matches', () => {
+    assert.equal(planInstruction(aircraft(), baseCtx()), null)
+  })
+
+  it('is deterministic for a given seed', () => {
+    const run = () =>
+      planInstruction(
+        aircraft({ distanceToFieldNm: 14, iasKts: 130, assignedSpeedKts: A320.approachKts }),
+        baseCtx({ rng: createRng('fixed'), leader: { distanceToFieldNm: 10, type: B77W } }),
+      )
+    assert.deepEqual(run(), run())
+  })
+})
+
+describe('renderInstruction — phraseology', () => {
+  const ctx = { rng: createRng('render'), station: 'Frankfurt Approach', runway: '25R' }
+
+  it('always names the aircraft in both the call and the readback', () => {
+    for (const kind of ['speed', 'vector', 'direct', 'handover', 'wake_hold', 'slot_hold', 'phase'] as const) {
+      const event = renderInstruction(
+        aircraft(),
+        {
+          kind,
+          callsign: 'BAW118',
+          speedKts: 180,
+          headingDeg: 250,
+          direct: { valid: true, fix: 'DOMUX', fixIndex: 2, savedNm: 16 },
+          handoverStation: 'Frankfurt Tower',
+          handoverFrequency: '119.900',
+        },
+        { ...ctx, rng: createRng(`render-${kind}`) },
+      )
+      assert.match(event.atcText, /BAW118/, `${kind} ATC call omits the callsign`)
+      assert.match(event.pilotReadbackText, /BAW118/, `${kind} readback omits the callsign`)
+    }
+  })
+
+  it('gives a Cessna "slowest practical speed" instead of a number', () => {
+    const event = renderInstruction(
+      aircraft({ type: C172, callsign: 'D-EKLM' }),
+      { kind: 'speed', callsign: 'D-EKLM', speedKts: 180 },
+      ctx,
+    )
+    assert.match(event.atcText, /slowest practical|as slow as practical/i)
+    assert.doesNotMatch(event.atcText, /180/)
+  })
+
+  it('reads the assigned speed back verbatim', () => {
+    const event = renderInstruction(aircraft(), { kind: 'speed', callsign: 'BAW118', speedKts: 190 }, ctx)
+    assert.match(event.atcText, /190 knots/)
+    assert.match(event.pilotReadbackText, /190/)
+  })
+
+  it('reads the handover frequency back — the one thing that must not be misheard', () => {
+    const event = renderInstruction(
+      aircraft(),
+      { kind: 'handover', callsign: 'BAW118', handoverStation: 'Frankfurt Tower', handoverFrequency: '119.900' },
+      ctx,
+    )
+    assert.match(event.atcText, /Frankfurt Tower/)
+    assert.match(event.pilotReadbackText, /119\.900/)
+  })
+
+  it('tells an arrival to continue approach but a departure to hold', () => {
+    const arrival = renderInstruction(aircraft({ phase: 'final' }), { kind: 'slot_hold', callsign: 'BAW118' }, ctx)
+    assert.match(arrival.atcText, /continue approach/i)
+    const departure = renderInstruction(aircraft({ phase: 'lineup' }), { kind: 'slot_hold', callsign: 'BAW118' }, ctx)
+    assert.match(departure.atcText, /hold (position|short)/i)
+  })
+
+  it('emits every instruction ATC-first', () => {
+    for (const kind of ['speed', 'vector', 'direct', 'handover', 'wake_hold', 'slot_hold', 'phase'] as const) {
+      const event = renderInstruction(aircraft(), { kind, callsign: 'BAW118', speedKts: 180 }, ctx)
+      assert.equal(event.order, 'atc_first', `${kind} must be ATC-first`)
+    }
+  })
+
+  it('emits an ambient check-in pilot-first — the aircraft calls, ATC answers', () => {
+    const event = renderInstruction(aircraft(), { kind: 'ambient', callsign: 'BAW118' }, ctx)
+    assert.equal(event.order, 'pilot_first')
+    assert.match(event.pilotReadbackText, /Frankfurt Approach/)
+  })
+
+  it('varies its wording across draws', () => {
+    const texts = new Set(
+      Array.from({ length: 20 }, (_, i) =>
+        renderInstruction(
+          aircraft(),
+          { kind: 'speed', callsign: 'BAW118', speedKts: 180 },
+          { ...ctx, rng: createRng(`variant-${i}`) },
+        ).atcText,
+      ),
+    )
+    assert.ok(texts.size > 1, 'template variants should produce more than one phrasing')
+  })
+
+  it('is deterministic for a given seed', () => {
+    const render = () =>
+      renderInstruction(aircraft(), { kind: 'phase', callsign: 'BAW118' }, { ...ctx, rng: createRng('fixed') })
+    assert.deepEqual(render(), render())
+  })
+})
diff --git a/tests/shared/aiTrafficIntegration.test.ts b/tests/shared/aiTrafficIntegration.test.ts
new file mode 100644
index 0000000..dec73f8
--- /dev/null
+++ b/tests/shared/aiTrafficIntegration.test.ts
@@ -0,0 +1,271 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { createRng } from '~~/shared/utils/aiTraffic/rng'
+import { createCallsignFactory, isCallsignDistinct } from '~~/shared/utils/aiTraffic/callsign'
+import { planInstruction, renderInstruction, applyDirect, cooldownSecFor } from '~~/shared/utils/aiTraffic/instructions'
+import { assessInTrail, nextFreeSlot } from '~~/shared/utils/aiTraffic/separation'
+import {
+  NM_PER_FIX,
+  advanceAircraft,
+  advancePhase,
+  createSimAircraft,
+  findLeader,
+  generateFixPool,
+  isArrival,
+  isDespawnable,
+} from '~~/shared/utils/aiTraffic/sim'
+import { MAX_ACTIVE_TRAFFIC, targetTrafficCount } from '~~/shared/data/trafficTiers'
+import type { RadioEvent } from '~~/shared/utils/aiTraffic/instructions'
+import type { SimAircraft } from '~~/shared/utils/aiTraffic/types'
+
+/**
+ * A long deterministic run of the pure sim core, wired the way useAiTraffic wires
+ * it. This is the closest thing to the real loop that runs without a browser: it
+ * catches the failures unit tests structurally cannot — runaway spawning, a
+ * wedged pending queue, separation that degrades over time, a callsign pool that
+ * collides once aircraft start cycling through it.
+ *
+ * It mirrors the composable's orchestration rather than importing it (the
+ * composable is Vue-bound); the RULES it exercises are the real, shipped ones.
+ */
+
+const USER_CALLSIGNS = ['DLH39A', 'DLH39A']
+const RUNWAY_SLOT_SEC = 90
+
+interface RunResult {
+  events: RadioEvent[]
+  pool: SimAircraft[]
+  maxPopulation: number
+  gapViolationTicks: number
+}
+
+function runSim(seed: string, ticks: number, target: number, gateOpen: () => boolean): RunResult {
+  const rng = createRng(seed)
+  const fixPool = generateFixPool(createRng(`${seed}|fixes`))
+  const callsigns = createCallsignFactory({ rng, tier: 'major', userCallsigns: USER_CALLSIGNS })
+
+  let pool: SimAircraft[] = []
+  let pending: RadioEvent[] = []
+  const events: RadioEvent[] = []
+  let nowSec = 0
+  let lastRadioAtSec = 0
+  let nextSpawnAtSec = 0
+  let ambientAfterSec = rng.int(45, 90)
+  let lastDeparture: { type: SimAircraft['type']; atSec: number } | null = null
+  let maxPopulation = 0
+  let gapViolationTicks = 0
+
+  const occupiedSlots = () => pool.filter(a => a.runwaySlot).map(a => a.runwaySlot!)
+
+  for (let t = 0; t < ticks; t++) {
+    nowSec += 1
+
+    for (const aircraft of [...pool]) {
+      advanceAircraft(aircraft, 1)
+      if (isDespawnable(aircraft)) {
+        callsigns.release(aircraft.callsign)
+        pool = pool.filter(a => a !== aircraft)
+        pending = pending.filter(e => e.callsign !== aircraft.callsign)
+      }
+    }
+
+    if (pool.length < target && nowSec >= nextSpawnAtSec && pool.length < MAX_ACTIVE_TRAFFIC) {
+      const generated = callsigns.next()
+      if (generated) {
+        const kind = rng.chance(0.6) ? 'arrival' : 'departure'
+        const aircraft = createSimAircraft(generated, kind, { rng, nowSec, frequency: '119.000', fixPool })
+        aircraft.runwaySlot = nextFreeSlot(
+          { fromSec: nowSec + 120, toSec: nowSec + 120 + RUNWAY_SLOT_SEC },
+          occupiedSlots(),
+        )
+        pool.push(aircraft)
+      }
+      nextSpawnAtSec = nowSec + rng.int(30, 120)
+    }
+    maxPopulation = Math.max(maxPopulation, pool.length)
+
+    // Separation health check across the arrival stream.
+    for (const aircraft of pool.filter(isArrival)) {
+      const leader = findLeader(aircraft, pool.filter(isArrival))
+      if (!leader) continue
+      const gap = assessInTrail({
+        leaderDistanceNm: leader.distanceToFieldNm,
+        leaderWake: leader.type.wake,
+        followerDistanceNm: aircraft.distanceToFieldNm,
+        followerWake: aircraft.type.wake,
+        followerKts: aircraft.iasKts,
+      })
+      if (gap.violated) gapViolationTicks++
+    }
+
+    if (pending.length === 0) {
+      for (const aircraft of pool) {
+        const plan = planInstruction(aircraft, {
+          nowSec,
+          rng,
+          leader: findLeader(aircraft, pool.filter(isArrival)),
+          occupiedSlots: occupiedSlots(),
+          lastDeparture,
+          handover: null,
+          nmPerFix: NM_PER_FIX,
+          silentForSec: nowSec - lastRadioAtSec,
+          ambientAfterSec,
+        })
+        if (!plan) continue
+        pending.push(renderInstruction(aircraft, plan, { rng, station: 'Frankfurt Approach', runway: '25R' }))
+        ambientAfterSec = rng.int(45, 90)
+        break
+      }
+    }
+
+    // Dispatch, gated exactly as the scheduler gates it.
+    if (pending.length && gateOpen()) {
+      const event = pending.shift()!
+      const aircraft = pool.find(a => a.callsign === event.callsign)
+      if (aircraft) {
+        events.push(event)
+        lastRadioAtSec = nowSec
+        const plan = event.plan
+        aircraft.quietUntilSec = nowSec + cooldownSecFor(plan)
+        if (plan.kind === 'speed' && plan.speedKts && aircraft.type.wake !== 'L') {
+          aircraft.assignedSpeedKts = plan.speedKts
+        } else if (plan.kind === 'vector') {
+          aircraft.vectorDelaySec += plan.vectorDelaySec ?? 90
+        } else if (plan.kind === 'direct' && plan.direct) {
+          applyDirect(aircraft, plan.direct)
+        } else if (plan.kind === 'phase') {
+          advancePhase(aircraft, rng, nowSec)
+          if (aircraft.phase === 'takeoff') lastDeparture = { type: aircraft.type, atSec: nowSec }
+        } else if (plan.kind === 'wake_hold') {
+          aircraft.nextEventAtSec = nowSec + (plan.holdSec ?? 60)
+        } else if (plan.kind === 'slot_hold' && aircraft.runwaySlot) {
+          // Mirrors the composable: a hold moves the reservation to the next free
+          // window, which is what stops the rule from re-firing every tick.
+          aircraft.runwaySlot = nextFreeSlot(
+            aircraft.runwaySlot,
+            occupiedSlots().filter(s => s !== aircraft.runwaySlot),
+          )
+          aircraft.nextEventAtSec = aircraft.runwaySlot.fromSec
+        }
+      }
+    }
+  }
+
+  return { events, pool, maxPopulation, gapViolationTicks }
+}
+
+describe('ai-traffic — a 30-minute run with an open frequency', () => {
+  const run = runSim('integration-open', 1800, 4, () => true)
+
+  it('keeps the frequency alive', () => {
+    assert.ok(run.events.length > 20, `expected a lively frequency, got ${run.events.length} calls in 30 min`)
+  })
+
+  it('does not flood it either — a real ATC reply must never queue behind a wall of chatter', () => {
+    // Every call is an ATC+readback pair of a few seconds of audio, and the queue
+    // is FIFO: sustained traffic denser than roughly one pair per 15 s would mean
+    // a real ATC reply always waits behind scenery. A busy major airport is ~2
+    // movements a minute on one frequency, so this is generous already.
+    const perMinute = run.events.length / 30
+    assert.ok(perMinute <= 4, `frequency is saturated: ${run.events.length} calls in 30 min (${perMinute.toFixed(1)}/min)`)
+  })
+
+  it('never nags one aircraft with the same instruction twice in a breath', () => {
+    // The failure this guards is the planner re-deriving an unresolved condition
+    // every tick — a vector, then another vector one second later, forever.
+    const bySeconds = new Map<string, number[]>()
+    run.events.forEach((e, i) => {
+      const key = `${e.callsign}|${e.kind}`
+      if (!bySeconds.has(key)) bySeconds.set(key, [])
+      bySeconds.get(key)!.push(i)
+    })
+    for (const [key, indices] of bySeconds) {
+      const repeats = indices.length
+      assert.ok(repeats < 12, `${key} was issued ${repeats} times in one 30-minute run`)
+    }
+  })
+
+  it('never exceeds the population cap that protects the speech queue and TTS budget', () => {
+    assert.ok(run.maxPopulation <= MAX_ACTIVE_TRAFFIC, `population hit ${run.maxPopulation}`)
+  })
+
+  it('never issues a callsign confusable with the user', () => {
+    for (const event of run.events) {
+      assert.ok(
+        isCallsignDistinct(event.callsign, USER_CALLSIGNS),
+        `${event.callsign} is confusable with ${USER_CALLSIGNS[0]}`,
+      )
+    }
+  })
+
+  it('never speaks the user callsign, in either half of a pair', () => {
+    for (const event of run.events) {
+      assert.doesNotMatch(event.atcText, /DLH\s?39A/i, `ATC call addressed the user: ${event.atcText}`)
+      assert.doesNotMatch(event.pilotReadbackText, /DLH\s?39A/i, `readback used the user callsign: ${event.pilotReadbackText}`)
+    }
+  })
+
+  it('never assigns a speed below the aircraft own approach speed', () => {
+    for (const event of run.events) {
+      if (event.plan.kind !== 'speed' || !event.plan.speedKts) continue
+      const aircraft = run.pool.find(a => a.callsign === event.callsign)
+      if (aircraft) assert.ok(event.plan.speedKts >= aircraft.type.approachKts, event.atcText)
+    }
+  })
+
+  it('resolves conflicts by slowing and vectoring rather than letting separation rot', () => {
+    // Some violation ticks are expected (that is what triggers a vector), but the
+    // stream must not spend its life inside the minima.
+    assert.ok(run.gapViolationTicks < 400, `separation was busted on ${run.gapViolationTicks} ticks`)
+  })
+
+  it('produces a varied mix of instruction types, not one rule firing forever', () => {
+    const kinds = new Set(run.events.map(e => e.kind))
+    assert.ok(kinds.size >= 3, `expected varied instructions, got: ${[...kinds].join(', ')}`)
+  })
+
+  it('always names an aircraft in every single transmission', () => {
+    for (const event of run.events) {
+      assert.ok(event.atcText.includes(event.callsign) || event.pilotReadbackText.includes(event.callsign))
+    }
+  })
+
+  it('is fully reproducible from its seed', () => {
+    const again = runSim('integration-open', 1800, 4, () => true)
+    assert.deepEqual(again.events.map(e => e.atcText), run.events.map(e => e.atcText))
+  })
+})
+
+describe('ai-traffic — a frequency the user never releases', () => {
+  it('stays completely silent, and does not lose the events it never got to speak', () => {
+    const run = runSim('integration-closed', 1800, 4, () => false)
+    assert.equal(run.events.length, 0, 'traffic transmitted while the gate was shut')
+    // The sim itself keeps running — aircraft still fly, they just say nothing.
+    assert.ok(run.pool.length > 0, 'the pool should still be populated')
+  })
+
+  it('resumes the moment the frequency frees up', () => {
+    let open = false
+    const rng = createRng('resume')
+    // Shut for the first half of the run, open for the second.
+    let tick = 0
+    const gate = () => { tick++; return open }
+    const first = runSim('integration-resume', 900, 4, gate)
+    assert.equal(first.events.length, 0)
+    open = true
+    const second = runSim('integration-resume', 900, 4, gate)
+    assert.ok(second.events.length > 0, 'traffic never came back after the gate reopened')
+    void rng
+  })
+})
+
+describe('ai-traffic — a dead GA field at 03:00', () => {
+  it('stays silent, because a target of zero is the correct answer', () => {
+    const target = targetTrafficCount('ga', 3)
+    assert.equal(target, 0)
+    const run = runSim('integration-night', 1800, target, () => true)
+    assert.equal(run.pool.length, 0)
+    assert.equal(run.events.length, 0)
+  })
+})
diff --git a/tests/shared/aiTrafficSeparation.test.ts b/tests/shared/aiTrafficSeparation.test.ts
new file mode 100644
index 0000000..cbdd8e5
--- /dev/null
+++ b/tests/shared/aiTrafficSeparation.test.ts
@@ -0,0 +1,193 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  TERMINAL_STANDARD_NM,
+  assessInTrail,
+  departureWakeDelaySec,
+  gapToTimeSec,
+  isGapViolated,
+  needsSpacing,
+  nextFreeSlot,
+  requiredGapNm,
+  slotIsFree,
+  slotsOverlap,
+  wakeSeparationNm,
+} from '~~/shared/utils/aiTraffic/separation'
+
+describe('wake separation matrix', () => {
+  it('reproduces the design table, leader → follower', () => {
+    assert.equal(wakeSeparationNm('J', 'H'), 6)
+    assert.equal(wakeSeparationNm('J', 'M'), 7)
+    assert.equal(wakeSeparationNm('J', 'L'), 8)
+    assert.equal(wakeSeparationNm('H', 'H'), 4)
+    assert.equal(wakeSeparationNm('H', 'M'), 5)
+    assert.equal(wakeSeparationNm('H', 'L'), 6)
+    assert.equal(wakeSeparationNm('M', 'L'), 5)
+  })
+
+  it('has no supplement where the standard already covers it', () => {
+    assert.equal(wakeSeparationNm('M', 'M'), 0)
+    assert.equal(wakeSeparationNm('M', 'H'), 0)
+    assert.equal(wakeSeparationNm('L', 'L'), 0)
+    assert.equal(wakeSeparationNm('L', 'M'), 0)
+    assert.equal(wakeSeparationNm('L', 'H'), 0)
+  })
+
+  it('is not symmetric — the leader is what generates the wake', () => {
+    assert.notEqual(wakeSeparationNm('H', 'L'), wakeSeparationNm('L', 'H'))
+  })
+})
+
+describe('requiredGapNm', () => {
+  it('is the design reading: a Medium behind a Heavy needs 5 NM, not 3+5', () => {
+    assert.equal(requiredGapNm('H', 'M'), 5)
+  })
+
+  it('falls back to the terminal standard for pairs with no supplement', () => {
+    assert.equal(requiredGapNm('M', 'M'), TERMINAL_STANDARD_NM)
+    assert.equal(requiredGapNm('L', 'L'), TERMINAL_STANDARD_NM)
+  })
+
+  it('never returns less than the terminal standard', () => {
+    for (const leader of ['L', 'M', 'H', 'J'] as const) {
+      for (const follower of ['L', 'M', 'H', 'J'] as const) {
+        assert.ok(requiredGapNm(leader, follower) >= TERMINAL_STANDARD_NM)
+      }
+    }
+  })
+})
+
+describe('gapToTimeSec', () => {
+  it('converts distance into time at the follower speed', () => {
+    assert.equal(gapToTimeSec(3, 180), 60)   // 3 NM at 180 kt = 1 minute
+    assert.equal(gapToTimeSec(5, 150), 120)
+  })
+
+  it('treats a stationary follower as never closing', () => {
+    assert.equal(gapToTimeSec(3, 0), Number.POSITIVE_INFINITY)
+    assert.equal(gapToTimeSec(3, -10), Number.POSITIVE_INFINITY)
+  })
+})
+
+describe('spacing thresholds', () => {
+  it('acts on the 20% buffer before the minimum is actually busted', () => {
+    // Required 5 NM → act below 6 NM, violated below 5 NM.
+    assert.equal(needsSpacing(6.1, 5), false)
+    assert.equal(needsSpacing(5.5, 5), true)
+    assert.equal(isGapViolated(5.5, 5), false)
+    assert.equal(isGapViolated(4.9, 5), true)
+  })
+
+  it('treats a violated gap as also needing action', () => {
+    assert.equal(needsSpacing(4.9, 5), true)
+  })
+})
+
+describe('departureWakeDelaySec', () => {
+  it('holds a Medium three minutes behind a Heavy', () => {
+    assert.equal(departureWakeDelaySec('H', 'M'), 180)
+    assert.equal(departureWakeDelaySec('H', 'L'), 180)
+    assert.equal(departureWakeDelaySec('J', 'M'), 180)
+  })
+
+  it('holds a Heavy two minutes behind a Heavy', () => {
+    assert.equal(departureWakeDelaySec('H', 'H'), 120)
+    assert.equal(departureWakeDelaySec('J', 'J'), 120)
+  })
+
+  it('imposes no time delay behind a non-heavy — runway occupancy covers it', () => {
+    assert.equal(departureWakeDelaySec('M', 'M'), 0)
+    assert.equal(departureWakeDelaySec('M', 'L'), 0)
+    assert.equal(departureWakeDelaySec('L', 'M'), 0)
+  })
+})
+
+describe('runway slots', () => {
+  it('detects overlap and treats touching slots as free', () => {
+    assert.equal(slotsOverlap({ fromSec: 0, toSec: 60 }, { fromSec: 30, toSec: 90 }), true)
+    assert.equal(slotsOverlap({ fromSec: 0, toSec: 60 }, { fromSec: 60, toSec: 90 }), false)
+    assert.equal(slotsOverlap({ fromSec: 60, toSec: 90 }, { fromSec: 0, toSec: 60 }), false)
+  })
+
+  it('detects full containment', () => {
+    assert.equal(slotsOverlap({ fromSec: 10, toSec: 20 }, { fromSec: 0, toSec: 100 }), true)
+  })
+
+  it('reports a slot free only when it clears everything', () => {
+    const occupied = [{ fromSec: 0, toSec: 60 }, { fromSec: 120, toSec: 180 }]
+    assert.equal(slotIsFree({ fromSec: 60, toSec: 120 }, occupied), true)
+    assert.equal(slotIsFree({ fromSec: 100, toSec: 130 }, occupied), false)
+    assert.equal(slotIsFree({ fromSec: 0, toSec: 10 }, []), true)
+  })
+
+  it('pushes a blocked slot past the blocker, preserving its duration', () => {
+    const slot = nextFreeSlot({ fromSec: 30, toSec: 90 }, [{ fromSec: 0, toSec: 60 }])
+    assert.deepEqual(slot, { fromSec: 60, toSec: 120 })
+  })
+
+  it('walks past a chain of back-to-back blockers', () => {
+    const occupied = [
+      { fromSec: 0, toSec: 60 },
+      { fromSec: 60, toSec: 120 },
+      { fromSec: 120, toSec: 200 },
+    ]
+    const slot = nextFreeSlot({ fromSec: 10, toSec: 40 }, occupied)
+    assert.deepEqual(slot, { fromSec: 200, toSec: 230 })
+    assert.equal(slotIsFree(slot, occupied), true)
+  })
+
+  it('leaves an already-free slot exactly where it was', () => {
+    const desired = { fromSec: 300, toSec: 360 }
+    assert.deepEqual(nextFreeSlot(desired, [{ fromSec: 0, toSec: 60 }]), desired)
+  })
+
+  it('only ever moves a slot later — simulated traffic yields, it never cuts in', () => {
+    const occupied = [{ fromSec: 100, toSec: 200 }]
+    for (let from = 0; from < 300; from += 17) {
+      const result = nextFreeSlot({ fromSec: from, toSec: from + 30 }, occupied)
+      assert.ok(result.fromSec >= from, `slot moved earlier: ${from} → ${result.fromSec}`)
+      assert.equal(slotIsFree(result, occupied), true)
+    }
+  })
+})
+
+describe('assessInTrail', () => {
+  const heavyLeaderMediumFollower = {
+    leaderDistanceNm: 10,
+    leaderWake: 'H' as const,
+    followerWake: 'M' as const,
+    followerKts: 180,
+  }
+
+  it('measures the 1D gap along the approach', () => {
+    const result = assessInTrail({ ...heavyLeaderMediumFollower, followerDistanceNm: 18 })
+    assert.equal(result.gapNm, 8)
+    assert.equal(result.requiredNm, 5)
+    assert.equal(result.needsAction, false)
+    assert.equal(result.violated, false)
+  })
+
+  it('flags a gap inside the buffer as needing action but not yet violated', () => {
+    const result = assessInTrail({ ...heavyLeaderMediumFollower, followerDistanceNm: 15.5 })
+    assert.equal(result.gapNm, 5.5)
+    assert.equal(result.needsAction, true)
+    assert.equal(result.violated, false)
+  })
+
+  it('flags a busted minimum', () => {
+    const result = assessInTrail({ ...heavyLeaderMediumFollower, followerDistanceNm: 14 })
+    assert.equal(result.violated, true)
+  })
+
+  it('clamps a follower that has somehow passed the leader to a zero gap', () => {
+    const result = assessInTrail({ ...heavyLeaderMediumFollower, followerDistanceNm: 5 })
+    assert.equal(result.gapNm, 0)
+    assert.equal(result.violated, true)
+  })
+
+  it('reports how long the gap lasts at the follower speed', () => {
+    const result = assessInTrail({ ...heavyLeaderMediumFollower, followerDistanceNm: 19 })
+    assert.equal(result.gapSec, gapToTimeSec(9, 180))
+  })
+})
diff --git a/tests/shared/aiTrafficSim.test.ts b/tests/shared/aiTrafficSim.test.ts
new file mode 100644
index 0000000..7ae9029
--- /dev/null
+++ b/tests/shared/aiTrafficSim.test.ts
@@ -0,0 +1,257 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { createRng } from '~~/shared/utils/aiTraffic/rng'
+import { findSimAircraftType } from '~~/shared/data/simAircraftTypes'
+import { PILOT_VOICES, pilotVoiceFor } from '~~/shared/utils/voicePool'
+import {
+  SPEED_DRIFT_KTS_PER_SEC,
+  advanceAircraft,
+  advancePhase,
+  createSimAircraft,
+  findLeader,
+  generateFixPool,
+  isArrival,
+  isDespawnable,
+  nextPhase,
+} from '~~/shared/utils/aiTraffic/sim'
+import type { SimAircraft, SimPhase } from '~~/shared/utils/aiTraffic/types'
+
+const A320 = findSimAircraftType('A320')!
+const B77W = findSimAircraftType('B77W')!
+
+function aircraft(overrides: Partial<SimAircraft> = {}): SimAircraft {
+  return {
+    callsign: 'BAW118',
+    callsignSpoken: 'Speedbird one one eight',
+    type: A320,
+    voiceId: 'nova',
+    phase: 'approach',
+    frequency: '119.000',
+    routeFixes: ['KOTAP', 'RIVAK'],
+    distanceToFieldNm: 20,
+    altitudeFt: 6000,
+    iasKts: 200,
+    assignedSpeedKts: null,
+    vectorDelaySec: 0,
+    runwaySlot: null,
+    nextEventAtSec: Number.POSITIVE_INFINITY,
+    quietUntilSec: 0,
+    ...overrides,
+  }
+}
+
+describe('generateFixPool', () => {
+  it('produces distinct, pronounceable 5-letter fixes', () => {
+    const fixes = generateFixPool(createRng('EDDF'), 8)
+    assert.equal(fixes.length, 8)
+    assert.equal(new Set(fixes).size, 8, 'fixes must be distinct')
+    for (const fix of fixes) assert.match(fix, /^[A-Z]{5}$/)
+  })
+
+  it('is deterministic per airport seed', () => {
+    assert.deepEqual(generateFixPool(createRng('EDDF')), generateFixPool(createRng('EDDF')))
+    assert.notDeepEqual(generateFixPool(createRng('EDDF')), generateFixPool(createRng('EDDM')))
+  })
+})
+
+describe('createSimAircraft', () => {
+  const generated = { callsign: 'BAW118', callsignSpoken: 'Speedbird one one eight', type: A320 }
+  const opts = { rng: createRng('spawn'), nowSec: 0, frequency: '119.000', fixPool: generateFixPool(createRng('EDDF')) }
+
+  it('spawns an arrival out on the STAR, descending', () => {
+    const ac = createSimAircraft(generated, 'arrival', { ...opts, rng: createRng('arr') })
+    assert.equal(ac.phase, 'inbound')
+    assert.ok(ac.distanceToFieldNm >= 25 && ac.distanceToFieldNm <= 60)
+    assert.ok(ac.altitudeFt >= 7000 && ac.altitudeFt <= 12000)
+    assert.ok(ac.iasKts <= 250, 'an inbound below 10,000 ft must not spawn above the speed limit')
+    assert.ok(ac.iasKts >= A320.approachKts)
+    assert.ok(ac.nextEventAtSec > 0 && Number.isFinite(ac.nextEventAtSec))
+  })
+
+  it('spawns a departure at the stand, stationary', () => {
+    const ac = createSimAircraft(generated, 'departure', { ...opts, rng: createRng('dep') })
+    assert.equal(ac.phase, 'taxi_out')
+    assert.equal(ac.distanceToFieldNm, 0)
+    assert.equal(ac.altitudeFt, 0)
+    assert.equal(ac.iasKts, 0)
+  })
+
+  it('gives the aircraft the voice its callsign hashes to', () => {
+    const ac = createSimAircraft(generated, 'arrival', opts)
+    assert.equal(ac.voiceId, pilotVoiceFor('BAW118'))
+    assert.ok(PILOT_VOICES.includes(ac.voiceId))
+  })
+
+  it('draws its route from the airport fix pool', () => {
+    const ac = createSimAircraft(generated, 'arrival', opts)
+    assert.ok(ac.routeFixes.length >= 2)
+    for (const fix of ac.routeFixes) assert.ok(opts.fixPool.includes(fix))
+  })
+
+  it('is deterministic for a given seed', () => {
+    const build = () => createSimAircraft(generated, 'arrival', { ...opts, rng: createRng('fixed') })
+    assert.deepEqual(build(), build())
+  })
+})
+
+describe('phase chains', () => {
+  it('walks an arrival to handoff', () => {
+    const chain: SimPhase[] = []
+    let phase: SimPhase = 'inbound'
+    for (let i = 0; i < 5; i++) { chain.push(phase); phase = nextPhase(phase) }
+    assert.deepEqual(chain, ['inbound', 'approach', 'final', 'rollout', 'handed_off'])
+  })
+
+  it('walks a departure to handoff', () => {
+    const chain: SimPhase[] = []
+    let phase: SimPhase = 'taxi_out'
+    for (let i = 0; i < 5; i++) { chain.push(phase); phase = nextPhase(phase) }
+    assert.deepEqual(chain, ['taxi_out', 'lineup', 'takeoff', 'climbout', 'handed_off'])
+  })
+
+  it('terminates at handed_off', () => {
+    assert.equal(nextPhase('handed_off'), 'handed_off')
+    assert.equal(isDespawnable(aircraft({ phase: 'handed_off' })), true)
+    assert.equal(isDespawnable(aircraft({ phase: 'final' })), false)
+  })
+
+  it('classifies arrivals and departures', () => {
+    for (const phase of ['inbound', 'approach', 'final', 'rollout'] as SimPhase[]) {
+      assert.equal(isArrival(aircraft({ phase })), true, phase)
+    }
+    for (const phase of ['taxi_out', 'lineup', 'takeoff', 'climbout'] as SimPhase[]) {
+      assert.equal(isArrival(aircraft({ phase })), false, phase)
+    }
+  })
+})
+
+describe('advancePhase', () => {
+  it('pins an arrival to its Vref once it turns final', () => {
+    const ac = aircraft({ phase: 'approach' })
+    advancePhase(ac, createRng('final'), 100)
+    assert.equal(ac.phase, 'final')
+    assert.equal(ac.assignedSpeedKts, A320.approachKts)
+    assert.ok(ac.nextEventAtSec > 100)
+  })
+
+  it('releases the speed restriction on climbout', () => {
+    const ac = aircraft({ phase: 'takeoff', assignedSpeedKts: 160 })
+    advancePhase(ac, createRng('climb'), 100)
+    assert.equal(ac.phase, 'climbout')
+    assert.equal(ac.assignedSpeedKts, null)
+  })
+
+  it('stops scheduling events once handed off', () => {
+    const ac = aircraft({ phase: 'rollout' })
+    advancePhase(ac, createRng('done'), 100)
+    assert.equal(ac.phase, 'handed_off')
+    assert.equal(ac.nextEventAtSec, Number.POSITIVE_INFINITY)
+  })
+})
+
+describe('advanceAircraft — 1D kinematics', () => {
+  it('closes an arrival on the field at its groundspeed', () => {
+    const ac = aircraft({ distanceToFieldNm: 20, iasKts: 180 })
+    advanceAircraft(ac, 60) // one minute at 180 kt = 3 NM
+    assert.ok(Math.abs(ac.distanceToFieldNm - 17) < 1e-9)
+  })
+
+  it('descends an arrival at the type descent rate', () => {
+    const ac = aircraft({ altitudeFt: 6000 })
+    advanceAircraft(ac, 60)
+    assert.equal(ac.altitudeFt, 6000 - A320.descentFpm)
+  })
+
+  it('climbs a departure away from the field', () => {
+    const ac = aircraft({ phase: 'climbout', altitudeFt: 2000, distanceToFieldNm: 3, iasKts: 180 })
+    advanceAircraft(ac, 60)
+    assert.equal(ac.altitudeFt, 2000 + A320.climbFpm)
+    assert.ok(ac.distanceToFieldNm > 3)
+  })
+
+  it('drags IAS toward the assigned speed at ~1 kt/s so phraseology stays honest', () => {
+    const ac = aircraft({ iasKts: 250, assignedSpeedKts: 180 })
+    advanceAircraft(ac, 10)
+    assert.equal(ac.iasKts, 250 - 10 * SPEED_DRIFT_KTS_PER_SEC)
+  })
+
+  it('never overshoots the assigned speed', () => {
+    const ac = aircraft({ iasKts: 185, assignedSpeedKts: 180 })
+    advanceAircraft(ac, 60)
+    assert.equal(ac.iasKts, 180)
+  })
+
+  it('accelerates as well as decelerates', () => {
+    const ac = aircraft({ iasKts: 150, assignedSpeedKts: 180 })
+    advanceAircraft(ac, 10)
+    assert.equal(ac.iasKts, 160)
+  })
+
+  it('burns a vector as time on the timeline instead of closing distance', () => {
+    const ac = aircraft({ vectorDelaySec: 90, distanceToFieldNm: 20, altitudeFt: 6000 })
+    advanceAircraft(ac, 30)
+    assert.equal(ac.vectorDelaySec, 60)
+    assert.equal(ac.distanceToFieldNm, 20, 'a vectored aircraft holds its distance to the field')
+    assert.equal(ac.altitudeFt, 6000)
+  })
+
+  it('resumes closing once the vector is flown out', () => {
+    const ac = aircraft({ vectorDelaySec: 10, distanceToFieldNm: 20 })
+    advanceAircraft(ac, 10)
+    assert.equal(ac.vectorDelaySec, 0)
+    advanceAircraft(ac, 60)
+    assert.ok(ac.distanceToFieldNm < 20)
+  })
+
+  it('never drives distance or altitude negative on landing', () => {
+    const ac = aircraft({ phase: 'final', distanceToFieldNm: 0.5, altitudeFt: 200, iasKts: 140 })
+    for (let i = 0; i < 200; i++) advanceAircraft(ac, 1)
+    assert.equal(ac.distanceToFieldNm, 0)
+    assert.equal(ac.altitudeFt, 0)
+  })
+
+  it('brakes on rollout without moving the aircraft backwards', () => {
+    const ac = aircraft({ phase: 'rollout', iasKts: 130, distanceToFieldNm: 0 })
+    advanceAircraft(ac, 10)
+    assert.equal(ac.iasKts, 80)
+    for (let i = 0; i < 60; i++) advanceAircraft(ac, 1)
+    assert.equal(ac.iasKts, 0)
+    assert.equal(ac.distanceToFieldNm, 0)
+  })
+
+  it('is a no-op for a non-positive tick', () => {
+    const ac = aircraft()
+    const before = { ...ac }
+    advanceAircraft(ac, 0)
+    advanceAircraft(ac, -5)
+    assert.deepEqual(ac, before)
+  })
+})
+
+describe('findLeader', () => {
+  const follower = aircraft({ callsign: 'BAW118', distanceToFieldNm: 20 })
+
+  it('picks the closest aircraft ahead on the approach', () => {
+    const near = aircraft({ callsign: 'DLH1', distanceToFieldNm: 15 })
+    const far = aircraft({ callsign: 'AFR2', distanceToFieldNm: 5 })
+    assert.equal(findLeader(follower, [far, near, follower])?.callsign, 'DLH1')
+  })
+
+  it('returns null when the aircraft is leading the sequence', () => {
+    const behind = aircraft({ callsign: 'DLH1', distanceToFieldNm: 30 })
+    assert.equal(findLeader(follower, [behind, follower]), null)
+    assert.equal(findLeader(follower, [follower]), null)
+    assert.equal(findLeader(follower, []), null)
+  })
+
+  it('ignores departures — they are not on the approach', () => {
+    const departure = aircraft({ callsign: 'DLH1', phase: 'climbout', distanceToFieldNm: 5, type: B77W })
+    assert.equal(findLeader(follower, [departure, follower]), null)
+  })
+
+  it('never returns the follower itself', () => {
+    const twin = aircraft({ callsign: 'BAW118', distanceToFieldNm: 10 })
+    assert.equal(findLeader(follower, [twin, follower]), null)
+  })
+})
diff --git a/tests/shared/trafficTiers.test.ts b/tests/shared/trafficTiers.test.ts
new file mode 100644
index 0000000..2bd1235
--- /dev/null
+++ b/tests/shared/trafficTiers.test.ts
@@ -0,0 +1,104 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  MAX_ACTIVE_TRAFFIC,
+  resolveTrafficTier,
+  targetTrafficCount,
+  timeOfDayFactor,
+  trafficTierFromFrequencies,
+} from '~~/shared/data/trafficTiers'
+
+describe('resolveTrafficTier', () => {
+  it('prefers the curated map over the heuristic', () => {
+    // EDDF publishes a full set of positions, but the curated answer wins either way.
+    assert.equal(resolveTrafficTier('EDDF', ['TWR']), 'major')
+    assert.equal(resolveTrafficTier('EDDH', ['DEL', 'GND', 'TWR', 'APP']), 'regional')
+  })
+
+  it('ignores casing and surrounding whitespace', () => {
+    assert.equal(resolveTrafficTier(' eddm '), 'major')
+  })
+
+  it('falls back to the frequency heuristic for unknown airports', () => {
+    assert.equal(resolveTrafficTier('ZZZZ', ['DEL', 'GND', 'TWR', 'APP']), 'major')
+    assert.equal(resolveTrafficTier('ZZZZ', ['GND', 'TWR']), 'regional')
+    assert.equal(resolveTrafficTier('ZZZZ', ['ATIS']), 'ga')
+  })
+
+  it('defaults to regional when nothing at all is known', () => {
+    assert.equal(resolveTrafficTier(undefined), 'regional')
+    assert.equal(resolveTrafficTier(null), 'regional')
+    assert.equal(resolveTrafficTier(''), 'regional')
+    assert.equal(resolveTrafficTier('ZZZZ', []), 'regional')
+  })
+})
+
+describe('trafficTierFromFrequencies', () => {
+  it('counts four distinct controller positions as major', () => {
+    assert.equal(trafficTierFromFrequencies({ frequencyTypes: ['DEL', 'GND', 'TWR', 'DEP'] }), 'major')
+  })
+
+  it('does not count ATIS as a controller position', () => {
+    assert.equal(trafficTierFromFrequencies({ frequencyTypes: ['ATIS', 'GND', 'TWR', 'CTR'] }), 'regional')
+  })
+
+  it('does not let duplicates inflate the count', () => {
+    assert.equal(trafficTierFromFrequencies({ frequencyTypes: ['TWR', 'TWR', 'TWR', 'TWR'] }), 'regional')
+  })
+
+  it('treats a tower-only field as regional and a towerless one as ga', () => {
+    assert.equal(trafficTierFromFrequencies({ frequencyTypes: ['TWR'] }), 'regional')
+    assert.equal(trafficTierFromFrequencies({ frequencyTypes: ['ATIS'] }), 'ga')
+    assert.equal(trafficTierFromFrequencies({ frequencyTypes: [] }), 'ga')
+  })
+
+  it('normalizes casing and junk entries', () => {
+    assert.equal(trafficTierFromFrequencies({ frequencyTypes: [' del ', 'gnd', 'twr', 'app', ''] }), 'major')
+  })
+})
+
+describe('timeOfDayFactor', () => {
+  it('covers every hour of the day with a positive factor', () => {
+    for (let h = 0; h < 24; h++) {
+      assert.ok(timeOfDayFactor(h) > 0, `hour ${h} has no factor`)
+    }
+  })
+
+  it('applies the design bands', () => {
+    assert.equal(timeOfDayFactor(3), 0.2)   // night
+    assert.equal(timeOfDayFactor(22), 0.2)
+    assert.equal(timeOfDayFactor(5), 0.2)
+    assert.equal(timeOfDayFactor(7), 1.3)   // morning bank
+    assert.equal(timeOfDayFactor(12), 1.0)  // day
+    assert.equal(timeOfDayFactor(18), 1.3)  // evening bank
+    assert.equal(timeOfDayFactor(21), 0.6)  // winding down
+  })
+
+  it('truncates a fractional hour to its band', () => {
+    assert.equal(timeOfDayFactor(21.9), 0.6)
+    assert.equal(timeOfDayFactor(22.1), 0.2)
+  })
+})
+
+describe('targetTrafficCount', () => {
+  it('keeps a major airport busy during the banks and calm at night', () => {
+    assert.equal(targetTrafficCount('major', 7), 5)   // 4 × 1.3 = 5.2 → 5
+    assert.equal(targetTrafficCount('major', 12), 4)
+    assert.equal(targetTrafficCount('major', 3), 1)   // 4 × 0.2 = 0.8 → 1
+  })
+
+  it('leaves a GA field dead at night', () => {
+    assert.equal(targetTrafficCount('ga', 3), 0)      // 1 × 0.2 = 0.2 → 0
+    assert.equal(targetTrafficCount('ga', 12), 1)
+  })
+
+  it('never exceeds the population cap that protects the speech queue', () => {
+    for (const tier of ['major', 'regional', 'ga'] as const) {
+      for (let h = 0; h < 24; h++) {
+        const n = targetTrafficCount(tier, h)
+        assert.ok(n >= 0 && n <= MAX_ACTIVE_TRAFFIC, `${tier}@${h} → ${n}`)
+      }
+    }
+  })
+})
diff --git a/tests/shared/voicePool.test.ts b/tests/shared/voicePool.test.ts
new file mode 100644
index 0000000..b1b8036
--- /dev/null
+++ b/tests/shared/voicePool.test.ts
@@ -0,0 +1,89 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  CONTROLLER_VOICES,
+  PILOT_VOICES,
+  RESERVED_VOICES,
+  controllerVoiceFor,
+  fnv1a,
+  pilotVoiceFor,
+  voiceFromPool,
+} from '~~/shared/utils/voicePool'
+
+describe('voicePool — partitions', () => {
+  it('keeps the controller and pilot partitions disjoint', () => {
+    const overlap = CONTROLLER_VOICES.filter(v => PILOT_VOICES.includes(v))
+    assert.deepEqual(overlap, [], 'a simulated pilot must never sound like the controller')
+  })
+
+  it('never hands a reserved voice to a simulated pilot', () => {
+    for (const reserved of RESERVED_VOICES) {
+      assert.equal(PILOT_VOICES.includes(reserved), false, `${reserved} is reserved`)
+    }
+  })
+})
+
+describe('voicePool — assignment', () => {
+  it('is deterministic: the same callsign always gets the same voice', () => {
+    const first = pilotVoiceFor('DLH472')
+    for (let i = 0; i < 20; i++) {
+      assert.equal(pilotVoiceFor('DLH472'), first)
+    }
+  })
+
+  it('ignores callsign casing', () => {
+    assert.equal(pilotVoiceFor('dlh472'), pilotVoiceFor('DLH472'))
+  })
+
+  it('only ever returns voices from the pilot pool', () => {
+    for (let n = 100; n < 400; n++) {
+      assert.ok(PILOT_VOICES.includes(pilotVoiceFor(`BAW${n}`)))
+    }
+  })
+
+  it('spreads a realistic callsign set over most of the pool', () => {
+    const callsigns = ['DLH472', 'BAW118', 'EZY93A', 'RYR4021', 'KLM61', 'AFR1234', 'THY7', 'SWR88']
+    const used = new Set(callsigns.map(cs => pilotVoiceFor(cs)))
+    assert.ok(used.size >= 4, `expected varied voices, got ${[...used].join(', ')}`)
+  })
+
+  it('skips a reserved voice instead of failing', () => {
+    // Reserve everything but one entry — every key must land on the survivor.
+    const survivor = PILOT_VOICES[2]!
+    const reserved = PILOT_VOICES.filter(v => v !== survivor)
+    for (const cs of ['DLH1', 'BAW2', 'EZY3', 'RYR4']) {
+      assert.equal(voiceFromPool(cs, PILOT_VOICES, reserved), survivor)
+    }
+  })
+
+  it('falls back to the raw pool if everything is reserved', () => {
+    const voice = voiceFromPool('DLH472', PILOT_VOICES, PILOT_VOICES)
+    assert.ok(PILOT_VOICES.includes(voice))
+  })
+
+  it('throws on an empty pool rather than returning undefined', () => {
+    assert.throws(() => voiceFromPool('DLH472', []), /empty voice pool/)
+  })
+
+  it('assigns controller voices from the controller partition (multi-voice)', () => {
+    for (const position of ['EDDF_TWR', 'EDDF_GND', 'EDDF_APP', 'EDDF_DEL']) {
+      assert.ok(CONTROLLER_VOICES.includes(controllerVoiceFor(position)))
+    }
+  })
+})
+
+describe('voicePool — fnv1a', () => {
+  it('matches the reference vectors', () => {
+    assert.equal(fnv1a(''), 0x811c9dc5)
+    assert.equal(fnv1a('a'), 0xe40c292c)
+    assert.equal(fnv1a('foobar'), 0xbf9cf968)
+  })
+
+  it('stays inside the unsigned 32-bit range', () => {
+    for (const s of ['DLH472', 'a very long callsign string that is not one', 'ß∆']) {
+      const h = fnv1a(s)
+      assert.ok(Number.isInteger(h) && h >= 0 && h <= 0xffffffff, `${s} → ${h}`)
+    }
+  })
+})