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/avatar.py

@@ -1,7 +1,7 @@
 # retoor <retoor@molodetz.nl>
 
 import requests
-from devplacepy.avatar import avatar_url, generate_avatar_svg
+from devplacepy.avatar import avatar_seed, avatar_url, generate_avatar_svg
 from tests.conftest import BASE_URL
 
 
@@ -76,6 +76,27 @@ def test_avatar_url_with_different_seeds():
     assert url1 != url2
 
 
+def test_avatar_seed_prefers_avatar_seed_field():
+    assert avatar_seed({"username": "alice", "avatar_seed": "seed-xyz"}) == "seed-xyz"
+
+
+def test_avatar_seed_falls_back_to_username():
+    assert avatar_seed({"username": "alice"}) == "alice"
+
+
+def test_avatar_seed_falls_back_when_seed_blank():
+    assert avatar_seed({"username": "alice", "avatar_seed": ""}) == "alice"
+    assert avatar_seed({"username": "alice", "avatar_seed": None}) == "alice"
+
+
+def test_avatar_seed_none_user():
+    assert avatar_seed(None) == ""
+
+
+def test_avatar_seed_empty_user():
+    assert avatar_seed({}) == ""
+
+
 def test_generate_avatar_svg_empty_seed_uses_fallback():
     svg = generate_avatar_svg("")
     assert isinstance(svg, str)

tests/unit/database.py

@@ -594,3 +594,77 @@ def test_text_search_clause_still_matches_text_fields(local_db):
     assert clause is not None
     rows = list(posts.find(clause, deleted_at=None))
     assert post_uid in {r["uid"] for r in rows}
+
+
+def _notification(user_uid, target_url, read=False):
+    uid = generate_uid()
+    get_table("notifications").insert(
+        {
+            "uid": uid,
+            "user_uid": user_uid,
+            "type": "comment",
+            "message": "someone replied",
+            "related_uid": generate_uid(),
+            "target_url": target_url,
+            "read": read,
+            "created_at": _now_db_helpers(),
+        }
+    )
+    return uid
+
+
+def _is_read(uid):
+    return bool(get_table("notifications").find_one(uid=uid)["read"])
+
+
+def test_mark_notifications_marks_exact_url(local_db):
+    from devplacepy.database import mark_notifications_read_by_target
+
+    user = _user_db_helpers()
+    uid = _notification(user, "/posts/abc-post")
+    assert mark_notifications_read_by_target(user, "/posts/abc-post") == 1
+    assert _is_read(uid) is True
+
+
+def test_mark_notifications_matches_anchor_prefix(local_db):
+    from devplacepy.database import mark_notifications_read_by_target
+
+    user = _user_db_helpers()
+    uid = _notification(user, "/posts/abc-post#comment-5")
+    assert mark_notifications_read_by_target(user, "/posts/abc-post") == 1
+    assert _is_read(uid) is True
+
+
+def test_mark_notifications_leaves_other_targets(local_db):
+    from devplacepy.database import mark_notifications_read_by_target
+
+    user = _user_db_helpers()
+    keep = _notification(user, "/posts/other-post")
+    assert mark_notifications_read_by_target(user, "/posts/abc-post") == 0
+    assert _is_read(keep) is False
+
+
+def test_mark_notifications_only_unread_counted(local_db):
+    from devplacepy.database import mark_notifications_read_by_target
+
+    user = _user_db_helpers()
+    _notification(user, "/posts/abc-post", read=True)
+    assert mark_notifications_read_by_target(user, "/posts/abc-post") == 0
+
+
+def test_mark_notifications_empty_args(local_db):
+    from devplacepy.database import mark_notifications_read_by_target
+
+    user = _user_db_helpers()
+    assert mark_notifications_read_by_target("", "/posts/abc") == 0
+    assert mark_notifications_read_by_target(user, "") == 0
+
+
+def test_mark_notifications_scoped_per_user(local_db):
+    from devplacepy.database import mark_notifications_read_by_target
+
+    owner = _user_db_helpers()
+    other = _user_db_helpers()
+    other_uid = _notification(other, "/posts/abc-post")
+    assert mark_notifications_read_by_target(owner, "/posts/abc-post") == 0
+    assert _is_read(other_uid) is False

tests/unit/models.py

@@ -0,0 +1,20 @@
+# retoor <retoor@molodetz.nl>
+
+import pytest
+from pydantic import ValidationError
+
+from devplacepy.models import GameLegacyForm
+
+
+def test_game_legacy_form_accepts_valid_key():
+    assert GameLegacyForm(key="multiplier").key == "multiplier"
+
+
+def test_game_legacy_form_rejects_empty_key():
+    with pytest.raises(ValidationError):
+        GameLegacyForm(key="")
+
+
+def test_game_legacy_form_rejects_overlong_key():
+    with pytest.raises(ValidationError):
+        GameLegacyForm(key="x" * 41)

tests/unit/schemas.py

@@ -133,3 +133,45 @@ def test_devii_delete_media_is_confirm_gated():
     blob = f"{delete.summary} {delete.description or ''}".lower()
     assert "soft delete" in blob
     assert "confirm" in blob
+
+
+def test_game_legacy_out_defaults():
+    from devplacepy.schemas import GameLegacyOut
+
+    out = GameLegacyOut(key="multiplier", name="Tech Debt Payoff", level=2, cost=5)
+    dumped = out.model_dump()
+    assert dumped["key"] == "multiplier"
+    assert dumped["level"] == 2
+    assert dumped["cost"] == 5
+    assert dumped["maxed"] is False
+
+
+def test_game_farm_out_exposes_stars_and_legacy():
+    from devplacepy.schemas import GameFarmOut, GameLegacyOut
+
+    farm = GameFarmOut(
+        stars=7,
+        steal_cooldown_seconds=120,
+        legacy=[GameLegacyOut(key="speed", level=1)],
+    )
+    dumped = farm.model_dump()
+    assert dumped["stars"] == 7
+    assert dumped["steal_cooldown_seconds"] == 120
+    assert dumped["legacy"][0]["key"] == "speed"
+
+
+def test_game_plot_out_steal_and_golden_fields():
+    from devplacepy.schemas import GamePlotOut
+
+    plot = GamePlotOut(
+        slot=0,
+        can_steal=True,
+        steal_coins=40,
+        steal_cooldown_seconds=600,
+        steal_reason="protected",
+        is_golden=True,
+    )
+    dumped = plot.model_dump()
+    assert dumped["steal_cooldown_seconds"] == 600
+    assert dumped["steal_reason"] == "protected"
+    assert dumped["is_golden"] is True

tests/unit/services/devrant/serializers.py

@@ -0,0 +1,48 @@
+# retoor <retoor@molodetz.nl>
+
+from devplacepy.services.devrant import serializers
+
+
+def _rant(author):
+    return serializers.serialize_rant(
+        {
+            "id": 1,
+            "uid": "post-1",
+            "user_uid": "u1",
+            "content": "hello",
+            "created_at": "2026-06-20T00:00:00+00:00",
+        },
+        authors={"u1": author},
+        comment_counts={},
+        user_scores={},
+        my_votes={},
+    )
+
+
+def test_rant_avatar_uses_seed_when_present():
+    rant = _rant({"id": 7, "username": "neo", "avatar_seed": "seed-abc"})
+    assert rant["user_avatar"]["i"] == "u/seed-abc.png"
+    assert rant["user_avatar_lg"]["i"] == "u/seed-abc.png"
+
+
+def test_rant_avatar_falls_back_to_username():
+    rant = _rant({"id": 7, "username": "neo"})
+    assert rant["user_avatar"]["i"] == "u/neo.png"
+
+
+def test_comment_avatar_uses_seed_when_present():
+    comment = serializers.serialize_comment(
+        {
+            "id": 3,
+            "uid": "c1",
+            "user_uid": "u1",
+            "content": "reply",
+            "created_at": "2026-06-20T00:00:00+00:00",
+        },
+        rant_id=1,
+        authors={"u1": {"id": 7, "username": "neo", "avatar_seed": "seed-abc"}},
+        user_scores={},
+        my_votes={},
+        score_map={},
+    )
+    assert comment["user_avatar"]["i"] == "u/seed-abc.png"

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 -------------------------------------------------