# Bazaar Item Unique ID And Offline Trading Rollout

## Purpose

This rollout converts persisted item identity and offline trader or buyer session state to the new production-safe model. The migration is designed for a maintenance window and explicitly clears any in-flight trader, buyer, and offline sessions during cutover.

Do not reopen the server until every verification step passes.

## Preconditions

- Schedule a maintenance window.
- Stop new logins before beginning the migration.
- Ensure the `world` binary you are deploying includes this branch.
- Ensure operators have credentials to run schema updates and database dump commands.

## Mandatory Backup

Take a backup before any schema or migration command:

```powershell
world database:dump --player-tables --login-tables --dump-path=backups --compress
```

If you use a separate database backup process, complete it before continuing.

## Local Dev Validation

Run these commands against the local dev database before production:

```powershell
world database:updates --skip-backup
world database:item-unique-ids --preflight --verbose
world database:item-unique-ids --migrate --verbose
world database:item-unique-ids --verify --verbose
```

Validate these gameplay scenarios after the migration:

- Two traders listing the same item at different prices.
- One trader changing a price without affecting another trader.
- Offline trader purchase.
- Offline buyer purchase.
- Parcel retrieval for rows that previously had missing `item_unique_id` values.
- Alternate bazaar shard search.

## Production Sequence

1. Bring the server into maintenance mode and stop new gameplay activity.
2. Take the mandatory backup.
3. Apply schema updates:

```powershell
world database:updates
```

4. Run the migration preflight:

```powershell
world database:item-unique-ids --preflight --verbose
```

5. If preflight reports missing schema, duplicate live item IDs, or other unexpected errors, stop and resolve them before continuing.
6. Run the migration:

```powershell
world database:item-unique-ids --migrate --verbose
```

This step clears active trader, buyer, and offline session state. Players must re-enter those modes after deploy.

7. Run final verification:

```powershell
world database:item-unique-ids --verify --verbose
```

8. Reopen the server only after verification passes.

## What Preflight And Verify Must Show

The migration is not complete unless all of the following are true:

- `inventory`, `sharedbank`, and `trader` contain no null or blank `item_unique_id` values.
- `character_parcels`, `character_parcels_containers`, and `inventory_snapshots` contain no null or blank `item_unique_id` values.
- `inventory`, `sharedbank`, and `trader` contain no duplicate `item_unique_id` groups.
- There are no cross-table duplicate live `item_unique_id` values across `inventory`, `sharedbank`, and `trader`.
- `offline_character_sessions` is empty after migration.
- `account.offline` has no rows left set to `1`.

## Rollback Criteria

Rollback instead of reopening the server if any of the following occur:

- `world database:updates` fails.
- `world database:item-unique-ids --preflight` reports missing required schema.
- `world database:item-unique-ids --migrate` or `--verify` reports missing IDs, duplicate IDs, or stale offline session state.
- Bazaar listing, offline trader, offline buyer, or parcel retrieval smoke tests fail after migration.

## Rollback Actions

1. Keep the server in maintenance mode.
2. Restore the database backup taken before the rollout.
3. Redeploy the previous server build.
4. Confirm login, trader, buyer, and parcel behavior on the restored build before reopening the server.

## Notes

- `world database:item-unique-ids --keep-trading-state` exists for non-production diagnostics only. Do not use it during production cutover.
- The migration command expects schema updates to have been applied first. If required tables or columns are missing, the command fails and should not be bypassed.