deadhead-space-freight-tycoon/memory-bank/change-requests/CR-002-open-markets.md

# Change Request CR-002 — Open Markets, Bays as HQs

**Project:** Deadhead: Space Freight Tycoon
**Applies to:** a build with Phases 1–10 and CR-001 (Faster Start) complete
**Do this:** as **Phase 10B**, after Phase 10A and before Phase 11
**Related docs:** `implementation-plan.md`, `change-request-faster-start.md`, `game-design-document.md`, `DECISIONS.md`

> **Numbering note (added when implemented):** the plan's §0.5 already used 27 (pilot location storage), 28 (Git hosting) and 29–34 (CR-001). The new decisions below numbered 0.5.27 and 0.5.28 are recorded as **0.5.35 Ship delivery** and **0.5.36 Undiscovered locations**. The error code `location_undiscovered` is the existing `location-undiscovered`.

---

## 1. Why

Contracts are currently only offered at locations where the player has a bay, and repositioning is only allowed to and from bay locations. A ship that delivers to a location without a bay (for example the Moon) is stranded: there is no contract board there, and it cannot reposition home.

The fix follows the American/Euro Truck Simulator model:

- **Every discovered location has a contract board (the freight market).** Any idle ship can pick up work wherever it is, which makes backhaul work.
- **Bays are HQs (like ATS garages).** You need a bay to hire pilots there, to take delivery of newly bought ships there, and to unassign pilots there. Bays no longer control where contracts are available.
- **Discovery still gates expansion.** An undiscovered location has no board until the player delivers there.

## 2. Rules for this change

- All rules in `implementation-plan.md` §0.1 still apply: steps in order, one commit per step, each step's test must pass, `packages/sim` stays pure, all numbers live in `packages/content`.
- **Do not write data migrations for old contract boards.** Resetting the dev and test databases is fine. Schema migrations are still required.
- Update existing tests whose expectations change. Do not delete a test unless §5 says the step is replaced.
- Update `architecture.md` for every schema or API change and `progress.md` after every step.
- Stop for the user's review at the end of Phase 10B.

## 3. Decision changes

Record these in `DECISIONS.md` and in `implementation-plan.md` §0.4 and §0.5.

**Glossary changes (§0.4)**
- **Bay** → A docking bay the player leases at a discovered location. It is an HQ: pilots are hired there, newly bought ships are delivered there, and pilots can be unassigned there. A bay does **not** control where contracts are offered.
- **Contract board** (new) → The freight market at a discovered location. Every discovered location has one per player per board period, whether or not the player has a bay there.
- **Deadhead** (new) → A reposition: a ship flying empty to another location. Fuel only, no payout, no XP.

**Replaced**
- **0.5.5 (Contract boards are stored)** → A board exists for every **discovered location**, per player, per period. It is generated on the first request in a period and stored; later requests in that period return the stored board. Every contract expires at the end of its board period. *(Amended by CR-019:)* a stored location board also records the qualifying fleet it was generated for, and reads hide jobs the current qualifying fleet can't complete (Step 19.3).
- **Step 3.14 rule (reposition only to a bay)** → An idle ship can deadhead from **any** location to **any discovered** location other than its current one, subject to the normal range and landing checks.

**New**
- **0.5.27 Ship delivery.** Buying a ship requires choosing one of the player's bays. The new ship appears there, idle and uncrewed.
- **0.5.28 Undiscovered locations.** Requesting the board of an undiscovered location fails with a `location_undiscovered` error. Deadheading to an undiscovered location is not allowed; only a contract delivery discovers a location.

**Unchanged (confirm, don't modify)**
- **0.5.2 Pilot locations.** Hiring happens at a player bay; unassigning is allowed only at a location with a player bay.
- **CR-001 deal.** The deal still includes the Earth bay.

## 4. Steps — Phase 10B

### Step 10B.1 — Sim: boards at any location
- Change the contract board generator's input from "the bay's location" to "the board's location". No other generation rules change.
- Rename any sim types or functions that say "bay board" to "location board".
- **Test:** The Step 3.9 tests still pass with a location input. Generating a board for the Moon with no bay data supplied anywhere works and is deterministic.

### Step 10B.2 — Sim: deadhead validation
- Reposition validation allows any origin. The destination must be discovered, must differ from the origin, and must pass the range and landing checks. The bay requirement is removed.
- Update the Step 3.14 tests.
- **Test:** A Courier idle at the Moon with no Moon bay can deadhead to Earth. Deadheading to an undiscovered location fails with `location_undiscovered`. Deadheading to the ship's own location fails. Deadheading out of range fails with the out-of-range reason. A deadhead record still has zero payout and zero XP.

### Step 10B.3 — Database: boards keyed by location
- Change `contract_boards` to be keyed by player, location, and board period (the tutorial board keeps its own key).
- Update `architecture.md`.
- **Test:** Migrations run on a fresh database and are a no-op the second time. Two boards for the same player and period at different locations can coexist; a second board for the same player, location, and period is rejected by a unique constraint.

### Step 10B.4 — Server: board endpoint for any discovered location
- Replace "get contract board for a bay" with "get contract board for a location" in the route catalog and server. Any discovered location works; an undiscovered location returns `location_undiscovered`.
- Update the Step 6.9 tests.
- **Test:** The Moon's board is returned for a player with no Moon bay. Two requests in the same period return the same board. Requesting Mars's board before discovery fails with `location_undiscovered`; after a delivery discovers Mars, it succeeds.

### Step 10B.5 — Server: no more stranded ships
- Contract dispatch works from any discovered location where the ship is idle (it already validates that the ship is at the contract's origin; confirm no bay check remains).
- Deadhead dispatch uses the Step 10B.2 rules.
- Update the Step 6.10 and 6.11 tests.
- **Test (the original bug):** A ship delivers Earth→Moon with no Moon bay. After arrival, the Moon's board is available, a Moon→Earth contract can be dispatched with that ship, and it resolves normally. Separately, the same ship can instead deadhead Moon→Earth.

### Step 10B.6 — Server: ship delivery to a bay
- Buying a ship takes a bay id. The ship appears idle and uncrewed at that bay's location. Buying without a bay, or with a bay the player doesn't own, fails.
- Update the Step 6.5 tests.
- **Test:** With bays at Earth and the Moon, buying a Freighter for the Moon bay places it at the Moon. Buying with no bay id fails with a validation error. Buying with another player's bay id fails and changes nothing.

### Step 10B.7 — Client: Contracts screen by location
- The Contracts screen's selector lists all discovered locations instead of bays. Each entry shows a badge with the number of idle ships there.
- Default selection: the location of the most recently arrived idle ship; otherwise Earth.
- Fleet screen: each idle ship gets a "Find work here" action that opens its location's board.
- Update the Step 9.4 tests.
- **Test:** Component test: the selector lists every discovered location and no undiscovered ones; idle-ship badges match state; the default is the most recently arrived idle ship's location; "Find work here" opens the right board.
- **Amended (decision 0.5.164):** "Find work here" is disabled when the ship can't be dispatched now: its pilot is resting (CR-004; rest beside service, CR-023/CR-027, included), it's in the shop for an upgrade, repair or service (CR-009/CR-026/CR-027), or it has no pilot. The button says why with the countdown that ends last ("Resting · 04:12", "In the shop · 12:30", "No pilot assigned") and re-enables on its own when it ends. Every ship, Independent pilots' included; the Contracts tab stays browsable.

### Step 10B.8 — Client: deadhead action
- Rename the Fleet screen's "Reposition" action to "Deadhead (fly empty)". It is available for every idle ship. The destination picker lists discovered locations; ones out of range or not landable are shown disabled with the reason. Show fuel cost and trip time for each.
- Update the Step 9.6 tests.
- **Test:** Component test: an idle ship at the Moon with no Moon bay shows the action; the picker excludes undiscovered locations and the ship's current location; an out-of-range destination is disabled with its reason; fuel and time match the sim.

### Step 10B.9 — Client: bays as HQs
- Market screen: "Buy" opens a bay picker ("Deliver to which HQ?"). With only one bay, preselect it.
- Locations screen and map panels: every discovered location has a "View contracts" link. The "Lease bay" action explains what a bay does: "Open an HQ here: hire pilots and take delivery of new ships at this location."
- Update the Step 9.8, 9.9, and 10.3 tests.
- **Test:** Component test: Buy shows the bay picker and sends the chosen bay id; with one bay it is preselected. Every discovered location shows "View contracts", with or without a bay. The lease action shows the HQ explanation.

### Step 10B.10 — Plan amendments and regression
- Apply the amendments in §5 to `implementation-plan.md`, and update `game-design-document.md` §4 and §10 to match §1 of this document.
- Run the full suite.
- **Test:** CI is green. Manual check: on a fresh account after the CR-001 deal, deliver to the Moon, pick up a Moon→Earth contract with the same ship, and deliver it back to Earth without leasing a Moon bay.

## 5. Amendments to `implementation-plan.md`

| Step | Change |
|---|---|
| 0.4, 0.5 | Apply §3 of this document. |
| 3.9 | Input is a location, not a bay (10B.1). |
| 3.14 | Deadhead rules replace reposition-to-bay (10B.2). |
| 5.3 | `contract_boards` keyed by player, location, and period (10B.3). |
| 6.5 | Ship purchase takes a bay id (10B.6). |
| 6.9 | Boards for any discovered location (10B.4). |
| 6.10, 6.11 | No bay checks on dispatch; deadhead rules (10B.5). |
| 9.4 | Selector lists discovered locations (10B.7). |
| 9.6 | "Deadhead (fly empty)" for every idle ship (10B.8). |
| 9.8, 9.9, 10.3 | Bay picker on purchase; "View contracts" everywhere; HQ explanation (10B.9). |
| 12.1 | The simulated player picks up contracts at whatever location its ships are at, and only deadheads when no eligible contract exists there. Add a check: across the whole run, no ship is ever idle with no eligible contract **and** no reachable deadhead destination. |
| 12.5 | After Mars is discovered, also confirm Mars's contract board is available without a Mars bay. |

## 6. Out of scope

Garage-style bay capacity or slot limits, bay upgrades, recurring bay rent, pilots that pick their own jobs from their home bay (ATS-style AI drivers), and anything else in `implementation-plan.md` §0.3.