feat: add per-user avatar seed regeneration with irreversible random avatar replacement

Implement a new `avatar_seed` column on the users table that overrides the username-based seed for Multiavatar generation. Introduce a null-safe `avatar_seed(user)` choke point in `avatar.py` that resolves `user.get("avatar_seed") or user.get("username")`, registered as a Jinja global so every render site (`_avatar_link.html`, `avatar_url(...)` calls, SEO `og_image`, issues ad-hoc dicts, devRant payload/PNG) propagates a regenerated seed. Add `POST /profile/{username}/regenerate-avatar` endpoint (owner-or-admin only) that writes a fresh `generate_uid()` to `avatar_seed`, invalidates the target's user cache, and audits `profile.avatar.regenerate`. The previous seed is overwritten and never stored, making regeneration irreversible. Document the feature in `AGENTS.md` and `README.md`, add the API endpoint to `docs_api.py`, and include the `regenerate_avatar` Devii tool in `CONFIRM_REQUIRED`.

tests/unit/services/game/economy.py

@@ -157,3 +157,71 @@ def test_farm_score_handles_legacy_null_columns():
     assert economy.farm_score(
         {"xp": 50, "prestige": None, "perk_yield": None, "streak": None}
     ) == 50
+
+
+# --- legacy upgrades ---------------------------------------------------------
+
+
+def test_legacy_for_known_and_unknown():
+    assert economy.legacy_for("multiplier") is not None
+    assert economy.legacy_for("does_not_exist") is None
+
+
+def test_legacy_cost_grows_with_level():
+    up = economy.legacy_for("multiplier")
+    assert economy.legacy_cost(up, 0) == up.base_cost
+    assert economy.legacy_cost(up, 2) > economy.legacy_cost(up, 1)
+
+
+def test_legacy_multiplier_steps():
+    assert economy.legacy_multiplier(0) == 1.0
+    assert economy.legacy_multiplier(3) == 1 + economy.LEGACY_MULT_STEP * 3
+
+
+def test_stars_for_refactor_scales_with_level_and_prestige():
+    assert economy.stars_for_refactor(0, 0) == economy.STAR_BASE
+    assert economy.stars_for_refactor(10, 0) == economy.STAR_BASE + 2
+    assert economy.stars_for_refactor(0, 2) == economy.STAR_BASE + 2
+
+
+def test_prestige_base_plots_adds_legacy_plots():
+    assert economy.prestige_base_plots(0) == economy.STARTING_PLOTS
+    assert economy.prestige_base_plots(3) == economy.STARTING_PLOTS + 3
+
+
+# --- steal economy -----------------------------------------------------------
+
+
+def test_effective_steal_grace_extends_with_defense():
+    assert economy.effective_steal_grace(0) == economy.STEAL_GRACE_SECONDS
+    assert economy.effective_steal_grace(2) == (
+        economy.STEAL_GRACE_SECONDS + economy.LEGACY_DEFENSE_GRACE * 2
+    )
+
+
+def test_effective_steal_fraction_drops_with_defense_and_has_floor():
+    assert economy.effective_steal_fraction(0) == economy.STEAL_FRACTION
+    assert economy.effective_steal_fraction(2) < economy.STEAL_FRACTION
+    assert economy.effective_steal_fraction(99) >= 0.1
+
+
+def test_steal_reward_coins_is_a_fraction_of_harvest():
+    crop = economy.crop_for("shell")
+    full = economy.effective_reward_coins(crop)
+    stolen = economy.steal_reward_coins(crop)
+    assert 0 < stolen <= full
+
+
+# --- golden crops ------------------------------------------------------------
+
+
+def test_is_golden_deterministic_and_bounded():
+    first = economy.is_golden("plot-7", "2026-06-20T00:00:00+00:00")
+    second = economy.is_golden("plot-7", "2026-06-20T00:00:00+00:00")
+    assert first == second
+    assert isinstance(first, bool)
+
+
+def test_is_golden_requires_both_args():
+    assert economy.is_golden("", "2026-06-20T00:00:00+00:00") is False
+    assert economy.is_golden("plot-7", "") is False

tests/unit/services/game/store.py

@@ -490,6 +490,93 @@ def test_prestige_resets_farm_and_increments(local_db):
     assert len(store.get_plots(farm["uid"])) == economy.STARTING_PLOTS
 
 
+# --- legacy upgrades ---------------------------------------------------------
+
+
+def test_upgrade_legacy_success_spends_stars(local_db):
+    user = _reset("unit_a")
+    _set(user, stars=100, legacy_multiplier=0)
+    cost = economy.legacy_cost(economy.legacy_for("multiplier"), 0)
+    result = store.upgrade_legacy(user, "multiplier")
+    assert result["level"] == 1
+    assert result["spent"] == cost
+    farm = store.get_farm(user["uid"])
+    assert int(farm["legacy_multiplier"]) == 1
+    assert int(farm["stars"]) == 100 - cost
+
+
+def test_upgrade_legacy_unknown_key(local_db):
+    user = _reset("unit_a")
+    _set(user, stars=100)
+    with pytest.raises(GameError):
+        store.upgrade_legacy(user, "telekinesis")
+
+
+def test_upgrade_legacy_maxed(local_db):
+    user = _reset("unit_a")
+    up = economy.legacy_for("multiplier")
+    _set(user, stars=100000, legacy_multiplier=up.max_level)
+    with pytest.raises(GameError):
+        store.upgrade_legacy(user, "multiplier")
+
+
+def test_upgrade_legacy_insufficient_stars(local_db):
+    user = _reset("unit_a")
+    _set(user, stars=0, legacy_multiplier=0)
+    with pytest.raises(GameError):
+        store.upgrade_legacy(user, "multiplier")
+
+
+# --- stealing ----------------------------------------------------------------
+
+
+def _ripen_past_grace(user, slot=0):
+    farm = store.get_farm(user["uid"])
+    past = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
+    plot = store._plot_at(farm["uid"], slot)
+    get_table("game_plots").update(
+        {"uid": plot["uid"], "planted_at": past, "ready_at": past}, ["uid"]
+    )
+
+
+def test_steal_transfers_coins_and_clears_plot(local_db):
+    owner = _reset("unit_owner")
+    thief = _reset("unit_thief", coins=0)
+    store.plant(owner, 0, "shell")
+    _ripen_past_grace(owner)
+    result = store.steal(thief, owner, 0)
+    assert result["coins"] > 0
+    assert _coins(thief) == result["coins"]
+    farm = store.get_farm(owner["uid"])
+    assert (store._plot_at(farm["uid"], 0).get("crop_key") or "") == ""
+
+
+def test_steal_protected_within_grace(local_db):
+    owner = _reset("unit_owner")
+    thief = _reset("unit_thief")
+    store.plant(owner, 0, "shell")
+    farm = store.get_farm(owner["uid"])
+    past = (datetime.now(timezone.utc) - timedelta(seconds=5)).isoformat()
+    plot = store._plot_at(farm["uid"], 0)
+    get_table("game_plots").update(
+        {"uid": plot["uid"], "planted_at": past, "ready_at": past}, ["uid"]
+    )
+    with pytest.raises(GameError):
+        store.steal(thief, owner, 0)
+
+
+def test_steal_cooldown_blocks_second_raid(local_db):
+    owner = _reset("unit_owner")
+    thief = _reset("unit_thief", coins=0)
+    store.plant(owner, 0, "shell")
+    _ripen_past_grace(owner)
+    store.steal(thief, owner, 0)
+    store.plant(owner, 0, "shell")
+    _ripen_past_grace(owner)
+    with pytest.raises(GameError):
+        store.steal(thief, owner, 0)
+
+
 # --- backwards compatibility -------------------------------------------------