# Shop System Decision — racked.ru

**Date:** 2026-05-07
**Author:** s8n
**Status:** Decision — supersedes AUDIT-2026-05-07 F-11
**Inputs:** RESEARCH-SHOP-GUI.md (S1), RESEARCH-AUCTION-HOUSE.md (S2), RESEARCH-SHOP-AH-HYBRID.md (S3)

---

## 1. Problem statement

Three things land on the same hot spot:

- EZShop is bespoke, hardcoded 27-slot, drop+click-only, ugly title — YOU500 wants 54-slot polish.
- AuctionHouse 1.4.6 (Kiranhart) works, but ships ARR with no `LICENSE` file and a recurring dupe history.
- We want a single coherent marketplace experience under `/pm` (canonical exec), not a salad of mismatched plugins.

Three agents researched independently. They disagree on the shape of the answer:

| Agent | Recommendation | Core argument |
|---|---|---|
| S1 (shop GUI) | EconomyShopGUI free + keep AH separate | Best free-tier shop UX, drop-in replacement |
| S2 (auction house) | Keep Kiranhart short-term, swap to Nexus or Elaine Qheart | License + dupe risk; UX parity in the GPL fork |
| S3 (hybrid) | ExcellentShop unified, GPL-3 | One jar, one theme, one update path |

This doc reconciles them.

---

## 2. Stack candidates side-by-side

| Stack | Plugins | Shop license | AH license | Unified GUI? | Player shops? | Dependency surface |
|---|---|---|---|---|---|---|
| **A. ExcellentShop unified** | ExcellentShop + CoinsEngine (or Vault bridge) + NightCore | GPL-3 | GPL-3 | Shared theme, separate menus | Optional Chest module | NightCore framework jar |
| **B. EconomyShopGUI + NexusAuctionHouse** | EconomyShopGUI free + NexusAH | Proprietary free-tier | MIT | No (two themes) | No | Vault |
| **C. Genesis (BSP) + Elaine Qheart AH** | Genesis + AuctionHousePlugin | MIT | GPL | No | Genesis addon | Vault |
| **D. Status quo** | EZShop + AuctionHouse 1.4.6 | Bespoke (us) | ARR no LICENSE | No | No | Vault |

---

## 3. License + project-health matrix

| Stack | License fit (AGPL-leaning) | Active? | 1.21.x verified | Dupe / exploit history | FOSS-ethics score |
|---|---|---|---|---|---|
| A. ExcellentShop | GPL-3, sources self-buildable | Yes — push 2026-04-27 | 1.21.8+ Java 21 | Clean | 5/5 |
| B. EconomyShopGUI + Nexus | Proprietary free + MIT | Both active; Nexus quieter | 1.21.11 / 1.21.6 | Clean | 3/5 |
| C. Genesis + Elaine | MIT + GPL | Genesis active; Elaine open beta | 1.21.1 (Genesis untested 1.21.4+) | Clean | 5/5 |
| D. Status quo | Bespoke + ARR | EZShop dead-bespoke; Kiranhart active | 1.21.x | Recurring dupes (AntiDupe band-aid exists) | 1/5 |

ExcellentShop is the only stack where **both** halves are GPL-3, both are actively maintained by the same dev (NightExpress), and source is self-buildable so we never ship a paywalled binary. Everything else either splits the license story across two projects or carries one proprietary half.

---

## 4. Visual mockup — recommended `/pm` shop GUI

ExcellentShop's Virtual Shop module, themed and aliased. Title kept clean per YOU500 ask.

```
+------------------------------------------------------------+
|                  racked.ru / pm shop                       |
+------------------------------------------------------------+
|  [BLK]  [ORE]  [FOO]  [MOB]  [RED]  [DYE]  [TLS]  [MSC]    |   <- 8 categories
|                                                            |
|  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]               |
|  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]               |   <- 36 item slots
|  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]               |      (4 rows x 9)
|  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]               |
|                                                            |
|  [<]    [SELLALL]    [/pm market]    [BAL: 1,234]   [>]    |   <- nav + AH jump
+------------------------------------------------------------+
```

54 slots total: 8 category icons (top), 36 items (4x9 grid), 9 footer (page nav, sellall shortcut, AH cross-link, balance, page indicator). Right-click any item = sell, left-click = buy. No donor stars, no rank-locked items in the default tier.

`/pm market` opens the shared-theme Auction House (ExcellentShop AH module) in the same skin, same fonts, same border palette — the polish unification S3 was after.

---

## 5. Recommendation — Stack A (ExcellentShop unified)

**Pick ExcellentShop + CoinsEngine.**

Why this beats S1's EconomyShopGUI:

- EconomyShopGUI's free tier is genuinely good for the *shop* but the auction module is paywalled. S1 was right that the shop is excellent; S1 was wrong to treat AH as out-of-scope, because we already need to swap Kiranhart (S2's finding). If we have to touch both anyway, replacing both with one GPL plugin beats replacing both with two unrelated plugins.
- "Free binary, closed source" is exactly the trap our philosophy memo (`project_racked_philosophy.md`) tells us to avoid when a real GPL alternative exists at parity.

Why this beats S2's Nexus / Elaine path:

- Nexus is BIN-only (no bidding). Players already use bidding on Kiranhart; removing it is a regression.
- Elaine Qheart's plugin is open beta with ~1k installs. The license is right, the maturity is not.
- ExcellentShop's AH module has BIN+bid+per-rank caps+tax — feature-parity with Kiranhart, GPL license, single-vendor support story.

S3 was directionally right. The fix vs S3 is mostly operational (alias commands under `/pm`, disable Chest module, build from source).

---

## 6. Migration cost

| Step | Effort | Risk |
|---|---|---|
| 1. Build ExcellentShop + CoinsEngine + NightCore from source on a builder pod | 1 evening | Low — `mvn package`, output jars |
| 2. Stage on dev container, replicate EZShop 8 categories into `virtual-shop/` YAML | 2-3 hours | Low — YAML, no schema gotchas |
| 3. Migrate AuctionHouse listings | **Cannot migrate active listings** — drain or expire current AH first; new AH starts empty | Medium — communicate to players |
| 4. Alias `/pm shop` → `/vshop`, `/pm market` → `/ah`, hide native cmds | 30 min via `commands.yml` | Low |
| 5. Disable Chest Shop module (we don't need it; QuickShop-Hikari is the future story) | 5 min config flag | None |
| 6. Smoke-test on staging: 54-slot layout, per-rank discount perms, sellall, AH listing+bid | Half day | Low |
| 7. Maintenance-window swap on live: stop server, drop EZShop+AuctionHouse jars, drop new jars, reload configs | 30 min downtime | Medium — see risk register |
| 8. Update `AUDIT-2026-05-07.md` F-11, update `/pm help`, post player notice | 1 hour | None |

**Total:** roughly one evening of build+stage + one half-day staging trial + one short maintenance window. No code changes to other plugins. AuthLimbo, chat plugin, LP prefixes — all untouched.

---

## 7. Risk register

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| ExcellentShop GPL build breaks on a future Paper API rev | Low | Medium | Pin a known-good tag; CI build on Forgejo runner |
| NightCore framework jar drift between ExcellentShop and CoinsEngine | Low | Medium | Lock both to the same release wave; smoke-test on each upgrade |
| Player backlash over draining current AH listings | Medium | Low | Two-week heads-up in `/pm news`; offer to refund stuck items manually |
| `/pm` alias collisions with existing chat plugin commands | Low | Low | Audit `/pm` namespace before swap; document in SYSTEM.md |
| ExcellentShop dev (NightExpress) goes dark | Low | High | Source is GPL-3 — we keep buildable copy; fall back to Stack C (Genesis + Elaine) only if needed |
| Per-rank discount permissions clash with LP prefixes-locked rule | Low | Low | Discount perms ride on rank perms, not prefix metadata — orthogonal to `feedback_lp_prefixes_locked.md` |
| YOU500-style player wants bidding back in identical Kiranhart UX | Medium | Low | ExcellentShop AH supports bid+BIN; theme tweaks deliver familiar feel |
| Build-from-source policy adds ops overhead | Certain | Low | Document in `nullstone-server/build-shop.md`; one-line `mvn package` script |

---

## 8. Decision

**Adopt Stack A — ExcellentShop unified, GPL-3, built from source.** Schedule the migration after the next AuthLimbo release window. Update audit F-11 to reference this doc. Keep S1's EconomyShopGUI and S2's Nexus / Elaine in the back pocket as fallbacks if ExcellentShop ever goes dark.
