[Epic] Caravan / Trading-Nomad Domain #545

A 5th DeityDomain — Caravan — built around two new favor verbs (NPC trade, exploration) and the mod's first player-to-player exchange surface (shrine-hosted trade table). First domain to ship a placeable capstone block.

Key decisions

• New domain, not a re-skin — full blessing/offering/ritual trees, own glyph (wagon-wheel / compass-rose), own color (saffron / road-ochre).
• Two favor sources — NPC trader trades (Trade branch) and chunk-transition exploration (Wayfaring branch). Both rarity/value-weighted with per-event caps so whale trades and AFK-in-a-chunk can't farm.
• Capstone = placeable shrine, not a stat boost — caravan_avatar_road grants a caravanshrine block that acts as a tier-1 altar and hosts the player trade table. One per player.
• Player trade is the canonical exchange surface — replaces the earlier /gift command proposal. Server-authoritative two-pane dialog with escrow, anti-switcheroo (offer change clears the other side's ready), distance leash (6 blocks), and crash/disconnect recovery. Zero item-loss is the bar.
• Civ milestone: prefer option 2 (new trade_hub milestone) over bumping united_front to 5 domains — keeps existing civ progression intact.
• Persistence: new DiscoveredChunks: HashSet<long> on PlayerProgressionData → DataVersion = 5. v4 → v5 migration loads empty (no retroactive favor).

Vertical slices

Phase 1 — domain visible + first favor source (NPC trade)

• 1. Add DeityDomain.Caravan enum + UI plumbing — Caravan: add DeityDomain enum value + UI plumbing #427
• 2. Blessing/offering/ritual JSON + new stat keys — Caravan: blessing/offering/ritual JSON + new stat keys #428
• 3. TraderTransactionFavorTracker + TraderPatches — Caravan: TraderTransactionFavorTracker + TraderPatches #429

Phase 2 — Wayfaring favor source

• 4. Persist DiscoveredChunks + bump DataVersion to 5 — Caravan: persist DiscoveredChunks + bump DataVersion to 5 #430
• 5. ExplorationFavorTracker (chunk-transition based) — Caravan: ExplorationFavorTracker (chunk-transition based) #431

Phase 3 — capstone block

• 6. Portable shrine block + BlockBehaviorCaravanShrine — Caravan: portable shrine block + BlockBehaviorCaravanShrine #432

Phase 4 — player-to-player trade table

• 7. Two-player trade dialog scaffolding (UI + state sync) — Caravan: two-player trade dialog scaffolding #433
• 8. Atomic swap + escrow + disconnect safety — Caravan: atomic swap + escrow + disconnect safety #434
• 9. Trade-table favor grants — Caravan: trade-table favor grants #435

Cross-cutting

• 10. Civilization milestone update for 5 domains — Caravan: civilization milestone update for 5 domains #436
• 11. Balance config knobs in GameBalanceConfig — Caravan: balance config knobs in GameBalanceConfig #437

Dependency graph

#427 ──┬──> #428 ──┬──> #429 ──> #437 (config)
       │          └──> #432 ──> #433 ──> #434 ──> #435 ──> #437
       └──> #436
#430 ──> #431 ──> #437

Phase 1 and Phase 2 land in parallel. Phase 4 is the long pole (escrow safety is the hardest).

Risks

• Item-loss in trade table — Caravan: atomic swap + escrow + disconnect safety #434 must cover every failure path (disconnect, crash, shrine break, full inventory, distance leash, server restart). Treat its acceptance criteria as a checklist, not a wishlist.
• VS 1.22 trader API — exact patch target unconfirmed; Caravan: TraderTransactionFavorTracker + TraderPatches #429 starts with ilspycmd verification.
• DataVersion bump — Caravan: persist DiscoveredChunks + bump DataVersion to 5 #430 is irreversible; land it once and don't revisit.
• Trader exploit surface — whale-trade cap (20) and rarity weighting in Caravan: TraderTransactionFavorTracker + TraderPatches #429 need playtest tuning; config knobs in Caravan: balance config knobs in GameBalanceConfig #437 let us fix without a release.

Plan doc

Originally docs/topics/planning/features/trading-nomad-domain/implementation-plan.md — removed in the 2026-05-28 docs cleanup. Plan content now lives in the slice issues themselves.