From f7fd6415a90fe23675cbf7d83a988cee4f3805e0 Mon Sep 17 00:00:00 2001 From: Erik Date: Thu, 25 Jun 2026 20:14:54 +0200 Subject: [PATCH] docs: design for suitbuilder CD-tier filter (CD0/CD1/CD2 toggles) Per-search filter selecting which crit-damage tiers are allowed on armor. Default (all allowed) is byte-identical to current behavior; "prefer highest allowed tier" falls out of existing scoring. Go-only (live solver); Python copy left frozen. Co-Authored-By: Claude Opus 4.8 --- ...06-25-suitbuilder-cd-tier-filter-design.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/plans/2026-06-25-suitbuilder-cd-tier-filter-design.md diff --git a/docs/plans/2026-06-25-suitbuilder-cd-tier-filter-design.md b/docs/plans/2026-06-25-suitbuilder-cd-tier-filter-design.md new file mode 100644 index 00000000..a17585c7 --- /dev/null +++ b/docs/plans/2026-06-25-suitbuilder-cd-tier-filter-design.md @@ -0,0 +1,85 @@ +# Suitbuilder CD-tier filter — design + +**Date:** 2026-06-25 +**Status:** Approved (pending spec review) +**Scope:** Live Go suitbuilder only (`go-services/inventory-go/`) + the static suitbuilder page (`static/suitbuilder.{html,js}`). **No changes** to the frozen `inventory-service/suitbuilder.py` (legacy rollback reference). + +## Goal + +Let the user restrict which **crit-damage tiers** (CD0 / CD1 / CD2) are allowed on **armor** pieces in a suit search, so they can build, e.g., all-CD1 suits or CD1/CD0-only suits. Among whatever tiers are allowed, the solver still prefers the highest (existing behavior) — so this is fundamentally a **filter**, not a scoring change. + +## Background — current state + +- The live suitbuilder is the Go solver (`suit_solver.go` / `suit_model.go` / `suit_http.go`), reached via browser → tracker `/inv/suitbuilder/search` → inventory-go `/suitbuilder/search`. Python is frozen on `python-legacy`. +- There is **no crit-damage filtering today.** CD0/CD1/CD2 armor all flows into the search. The only thing distinguishing tiers is scoring (`CritDamage1: +10`, `CritDamage2: +20`) and the CD-descending armor sort — which is why CD2 always wins. +- The UI already shows **Crit Damage min/max** number inputs (`suitbuilder.html:54-57`), and the JS already sends `min_crit_damage`/`max_crit_damage` (`suitbuilder.js:310-311, 386-387`). The Go solver receives them into `SearchConstraints.MinCritDamage`/`MaxCritDamage` but **never references them** — dead, half-wired scaffold. This feature replaces that dead control. + +## Behavior contract + +- A new per-search filter selects which CD tiers are **allowed on armor**: independent CD0 / CD1 / CD2 toggles. +- **A checked tier = "allowed."** "Prefer higher, fall back lower" happens automatically among the allowed tiers via the existing scoring/sort — no scoring change. +- **Default = all three allowed.** Because the solver prefers the highest allowed tier, the default naturally leads with CD2 — i.e. identical to today's behavior. This is the "default CD2" state. +- **Empty / none-selected = treated as the default** (all allowed). A search can never be forced into an armorless state by this control. +- **Jewelry and clothing are never filtered by CD** — they are categorized separately in `loadItems` and the filter only touches armor. +- **Tier mapping** (handles rare high-crit gear): `CD0 = rating ≤ 0`, `CD1 = rating == 1`, **`CD2 = rating ≥ 2`**. A CD3+ gear piece counts as CD2 and is not silently dropped. + +### Worked examples + +| Allowed set | Result | +|---|---| +| `{0,1,2}` (default / empty) | Unchanged from today — prefer CD2, fall back CD1, CD0 | +| `{0,1}` | No CD2 armor; prefer CD1, fall back CD0 | +| `{1}` | All-CD1 suits; a slot with no CD1 piece is left empty | +| `{1,2}` | No CD0 armor; prefer CD2, fall back CD1 | + +## Backend design — `go-services/inventory-go` + +### 1. Constraint field (`suit_model.go`) +- Add `AllowedCritDamage []int \`json:"allowed_crit_damage"\`` to `SearchConstraints`. +- **Remove** the dead `MinCritDamage *int` / `MaxCritDamage *int` fields (never wired; their UI is being replaced). Leave the other unrelated dead fields (`MinArmor`/`MaxArmor`/`MinDamageRating`/`MaxDamageRating`) untouched — out of scope. + +### 2. Precompute the allowed set (`newSolver`, `suit_solver.go`) +- Build `allowedCD map[int]bool` by normalizing each value in `AllowedCritDamage` to a tier in `{0,1,2}` (clamp ≥2 to 2, ≤0 to 0). +- **Filter inactive** (no-op) when the resulting set is empty **or** already contains all of `{0,1,2}`. This makes "all checked", "none checked", and "field absent" all mean *no filter* — and guarantees the default path is byte-identical to current output. + +### 3. Apply the filter in `loadItems` (`suit_solver.go`) +- **Location & ordering are load-bearing:** filter armor items **after** the raw `items` slice is built (~line 254) and **before `removeSurpassedItems`** (line 262). If the CD filter ran after domination, a CD2 piece could dominate and remove an allowed CD1 piece, which we'd then exclude — leaving the slot needlessly empty. Filtering first keeps domination confined to allowed items. +- An item is "armor" iff its slot matches `armorSlotSet` (including comma-joined multi-coverage slots like `"Chest, Abdomen"`). Factor a small package-level helper `isArmorSlot(slot string) bool` (mirrors the existing `matches(it.Slot, armorSlotSet, nil)` logic) so it can be used both here and in the existing categorization pass. Non-armor items (jewelry/clothing/unknown) are never dropped by this filter. +- When the filter is active, drop armor items whose normalized tier ∉ `allowedCD`. +- Tailored/reduced armor inherits its CD from the origin piece (already filtered upstream), so reductions of excluded pieces never appear — no extra handling needed. + +### Regression safety +- The default (no `allowed_crit_damage`, or all three) path must produce **identical** output to the current solver. The no-op guard in step 2 ensures this. + +## Frontend design — `static/suitbuilder.{html,js}` + +(Vanilla static page served from the bind-mounted `static/` — no build step, no container restart.) + +### 1. `suitbuilder.html` (~lines 53-58) +- Replace the `Crit Damage [Min]-[Max]` number inputs (`#minCritDmg`, `#maxCritDmg`) with three checkboxes inside the existing `filter-group`: `#allowCD0`, `#allowCD1`, `#allowCD2`, labelled CD0 / CD1 / CD2, **all `checked` by default.** Keep the surrounding `filter-row`/`filter-group`/`constraint-section` layout. + +### 2. `suitbuilder.js` +- **`gatherConstraints()` (lines 310-311):** remove the `min_crit_damage`/`max_crit_damage` reads; add `allowed_crit_damage`, an array of the checked tiers, e.g. `[0,1,2]`. +- **`validateConstraints()` (line 360):** remove the now-deleted `!constraints.min_crit_damage` term from the "at least one constraint" check. (A CD restriction is not a valid *standalone* search — armor is only loaded for the chosen primary/secondary set, so a set/cantrip/ward/rating-min is still required. The CD filter is a refinement on top.) +- **`streamOptimalSuits()` (lines 386-387):** remove `min_crit_damage`/`max_crit_damage` from `requestBody`; add `allowed_crit_damage: constraints.allowed_crit_damage`. + +## Testing + +- **Regression (Go):** a default search (no `allowed_crit_damage`) yields output identical to baseline — assert the no-op path. Where existing suitbuilder validation/golden harnesses exist (`compare/`), the default case must stay byte-identical; filtered cases are intentionally Python-divergent and are validated by the new tests below, not against Python. +- **New unit test (Go):** + - `allowed=[1]` ⇒ every armor piece in every returned suit has tier CD1; jewelry/clothing still present. + - `allowed=[0,1]` ⇒ no CD2 armor appears in any suit. + - `allowed=[1,2]` ⇒ no CD0 armor appears. + - `allowed=[]` / `[0,1,2]` ⇒ identical to baseline. +- **Manual:** on the server, run a real CD1-only search and confirm all-CD1 armor and sane fallback/empty-slot behavior. + +## Deploy + +- **Backend:** rebuild `inventory-go` on the server (sync `go-services/`, build, recreate with the cutover override) — see MosswartOverlord CLAUDE.md "Go services — build, deploy, gotchas". +- **Frontend:** edit `static/suitbuilder.{html,js}`; a normal `git pull` on the host picks them up via the bind mount — no build, no restart. + +## Out of scope + +- `inventory-service/suitbuilder.py` (frozen/legacy) — intentionally left to diverge. +- The other dead constraint fields (`min/max_armor`, `min/max_damage_rating`) — separate follow-up if wanted. +- No scoring-weight changes; no new scoring knobs.