CargoWreck — Schema

Status: ✅ Shipped — the CargoWreck salvage subsystem is live: salvage_service.py spawns a wreck on ship destruction, the JSONB cargo map decrements as players salvage and the row deletes at the {} terminal, and the 1-hour original-owner / team-mate / killing-blow exemption window (ADR-0007 + ADR-0055 S-F2) gates outside-team salvagers behind Suspect flagging.

Salvageable wrecks left in a sector when a ship is destroyed. Companion docs: ../FEATURES/gameplay/ships.md#cargo-wreck, ../ADR/0007-s8-cargo-wreck-mechanic.md.

---

CargoWreck

Wrecks are created when a ship is destroyed and persist in the sector until salvaged.

Source: services/gameserver/src/models/cargo_wreck.py; services/gameserver/src/services/salvage_service.py.

Purpose: Salvageable container of cargo dropped into a sector by a destroyed ship. Visible to all players in the host sector; salvageable by anyone with cargo space, with the first hour gated by the original-owner / team-mate exemption (early salvagers from outside the team trigger Suspect Status — see ../FEATURES/gameplay/ships.md#cargo-wreck).

Fields:

name	type	constraints	notes
id	UUID	PK
sector_id	UUID FK sectors.id	not null, CASCADE	host sector
original_owner_id	UUID FK players.id	nullable	the player whose ship was destroyed; null if NPC ship
original_team_id	UUID FK teams.id	nullable	snapshot of the original owner's team at destruction time; team mates inherit the grace-period exemption
killing_blow_pilot_id	UUID FK players.id	nullable	per ADR-0055 S-F2 — the individual pilot whose hit destroyed the ship. Inherits grace-period exemption alongside the original owner + team. Null for non-combat causes (HAZARD, ABANDONMENT_EXPIRED) and for SELF_DESTRUCT (no wreck spawns anyway).
destroyed_ship_id	UUID FK ships.id	nullable	reference to the now-destroyed ship row; nullable in case of cascade
destroyed_ship_type	Enum ship_type	not null	for UI display ("Cargo Hauler wreck")
damage_type	Enum weapon_type	not null	drives the recovery band per commodity
cargo	JSONB	not null	{commodity_name: int} — remaining salvageable cargo. Decrements as players salvage.
created_at	DateTime	not null	wreck creation timestamp; the 1-hour grace window is computed from this
cause	Enum wreck_cause	not null	COMBAT / HAZARD / SELF_DESTRUCT / ABANDONMENT_EXPIRED (matches the Ship.destruction_cause enum per ./ships.md; WARP_GATE_ANCHOR is not in wreck_cause because anchor destructions do not spawn a Cargo Wreck per ADR-0029)

Relationships: - sector → Sector (FK — see ./galaxy.md#sector). - original_owner → Player (FK, nullable). - original_team → Team (FK, nullable). - destroyed_ship → Ship (FK, nullable — see ./ships.md).

Lifecycle: Created by CombatService / ShipService on destruction; updated as players salvage; deleted when cargo becomes empty {}. No decay timer — wrecks persist until fully salvaged.

Indexes: (sector_id) for sector-presence queries; (original_owner_id, created_at) for "my recent wrecks" queries; (killing_blow_pilot_id, created_at) for "wrecks I'm entitled to scoop during grace" queries.