perf: represent fort ids as a 17-byte value type

[jfberry]

Supersedes #395. Stacked on c/golbat-memory-persistence-6846cc (#394) — the diff below is this branch's 17 commits only.

Replaces string interning with a fixed-width value type for fort ids, and makes pokemon username persistence opt-in.

Why this and not interning

#395 proposed 4-byte handles into a global intern table. Before committing to that, both shapes were benchmarked against each other at production scale (2M forts, 3.25M pokemon, this repo's own rtree/xsync versions). Results are in the comment on #395; the short version:

	string	uint32 handle	[16]byte+suffix
Forced-GC median	177 ms	128 ms	126 ms
Heap objects	20.6M	19.4M	15.3M
Scan inner loop (2M forts)	181 µs	99 µs	162 µs

On GC — the metric this work exists for — the two options tie. So the decision came down to structure: the value type deletes a category of machinery (global table, unbounded growth, deleted-fort leak, resolve-failure paths at ~35 emit sites) rather than engineering around it, and drives heap objects to the floor. The handle's real advantage is scan throughput, and fort scans are low-traffic today; interning on top of value ids stays available if that changes.

The type

Fort ids are a 128-bit hex GUID plus an optional two-hex-digit suffix, stored as varchar(35):

type FortId struct {
	Guid   [16]byte
	Suffix uint8 // parsed value, raw; 0 = the bare 32-char form
}

17 bytes, comparable, pointer-free — so it is used directly as cache keys, map keys and R-tree payloads, with string conversion only at DB/JSON/webhook/proto boundaries.

Three properties are load-bearing and each is pinned by a test:

• The suffix is not enumerated. Any two lowercase hex digits parse, so a new Niantic suffix needs no code change. A census of a production instance found .16/.11/.12 on pokestops and gyms and .23/.16/.11/.12 on stations — the set is not per-fort-type.
• Bare 32-char ids are a live shape, not legacy junk. They are sponsored forts (EE, Community Ambassador Location, Play! Pokémon Store), several updated within the hour of the census. They are treated as Niantic's stripped null suffix, which is also what makes byte order match varchar order: the bare form sorts first, and lowercase hex ascends in ASCII exactly as it ascends in value. That congruence is what lets the write-behind deadlock-avoidance sort stay consistent with ORDER BY id.
• The zero value is the absent/"None" sentinel, so ParseFortId refuses to produce it — an all-zero GUID with no suffix is rejected, as is "". Exactly one nonconforming id exists in the censused production database (a pokestop with id = ''); it now fails to load with an error log rather than aliasing "no fort".

Wire and schema compatibility

Nothing observable changes. Schema untouched (git diff -- sql/ is empty). API and webhook DTO fields stay string/*string with conversion at the assignment site, so the JSON contract is unchanged — including "pokestop_id": "None" in the pokemon webhook and null (never "") in API responses, both pinned by tests.

Value()/Scan() render and read the same varchar. TestPokemonFullRowRoundTrip reads pokestop_id back as a raw string rather than through FortId.Scan — the only check that catches a Valuer regression, since a self-consistent Scanner/Valuer pair could write garbage into the column and never notice. sqlx.In's reflective expansion of []FortId is pinned separately, because a mistake there is a silently wrong DELETE.

Username

username is no longer persisted by default. New store_username option (default false); the reporting account is threaded from the decode context to its two real consumers — the webhook payload and the shiny/duplicate-encounter dedup.

Both consumers now prefer the live account over the stored one. This is a fix, not just plumbing: the dedup needs the account reporting now, and preferring a frozen stored value would make SetAccountSeen report "already seen" for every distinct account after the first, dropping their shiny checks from the odds statistics before the counters ran.

With the option off, webhooks carry the account that triggered the save rather than the first account to see the pokemon, and ProactiveIVSwitch webhooks (which have no account context) carry "username": null.

Measured size effect

PokemonData 256 → 248 bytes, Pokemon 352 → 344, allocator class unchanged at 352. PokestopId moved out of the pointer group into the 1-byte group, where 17 bytes fill existing padding rather than create it. Station and Incident each grew 8 bytes, also without changing class. The struct-level effect is a wash; the win is ~3.25M fewer heap-allocated strings, which unsafe.Sizeof cannot see.

Testing

Green under both build tags, -race, and golangci-lint v2.12.2. Three MariaDB round-trip tests verified against a real 11.4 instance with migrations applied, including that rows written before this change still load. Every task's diff was reviewed independently, and a whole-branch review re-ran all gates.

Before deploying

FortId.Scan now gates six more columns than the census covered: pokemon.pokestop_id, incident.pokestop_id, route.start_fort_id, route.end_fort_id, tappable.fort_id, station_battle.station_id. A malformed value makes that row unloadable — logged and skipped, blast radius one row. pokemon.pokestop_id is the one to check: the previous code could write '' there unguarded, and with preserve_pokemon enabled every such row is skipped at startup. Worth a SELECT COUNT(*) WHERE <col> = '' per column so any startup noise is a known quantity.

Design doc: docs/superpowers/specs/2026-08-18-fortid-value-type-design.md.

🤖 Generated with Claude Code