District unlock event history: persist unlock events per agent for replay and debugging

[leocagli]

Context

District unlocks fire district.unlocked events but currently there is no persistent log of which agent unlocked which district and when. This makes debugging gamification bugs ("why didn't this agent unlock district 3?") hard.

What to implement

Event log store

On every district.unlocked event, append to a per-agent log:

interface DistrictUnlockEvent {
  agentId: string
  districtId: string
  unlockedAt: string   // ISO timestamp
  xpAtUnlock: number   // agent's XP at the moment of unlock
}

Route: GET /api/agents/:id/districts/history

Returns the agent's full district unlock history, sorted by unlockedAt descending.

Response:

{
  "agentId": "bot-1",
  "unlocks": [
    { "districtId": "district-3", "unlockedAt": "2026-06-26T10:00:00Z", "xpAtUnlock": 1200 }
  ]
}

No duplicates

If the same district is unlocked twice (edge case), dedupe by districtId keeping the earliest unlock.

Acceptance criteria

• Unlocking a district appends an entry with correct agentId, districtId, and xpAtUnlock
• GET /api/agents/:id/districts/history returns entries sorted newest-first
• Duplicate district unlock: only the first entry kept
• Agent with no unlocks returns { unlocks: [] }
• Unit tests: single unlock, multiple districts, dedup, empty agent

[Glam26]

I've implemented similar event history and audit logging features before, building append-only activity logs with deduplication, timestamped records, and query endpoints for debugging and analytics. I'm comfortable designing lightweight persistence layers and ensuring event handlers remain idempotent.

For this task, I'll add a persistent per-agent district unlock history, record the unlock timestamp and XP at unlock, expose a GET /api/agents/:id/districts/history endpoint with newest-first ordering, prevent duplicate entries by retaining the earliest unlock, and add comprehensive unit tests covering single unlocks, multiple unlocks, deduplication, and empty histories.

[grantfox-oss]

🦊 GrantFox — @Glam26 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #319)
2. Your PR will be reviewed by the Bitcoindefi maintainers

Good luck! Track your progress on GrantFox.