fix(link): a protocol bump owes four declaration sites, not three #175

wtclaude · 2026-08-25T00:24:12Z

wtclaude commented

2026-08-25 00:24:12 +00:00

Why

v4.md §5's cross-repo obligation table gave module-uo one row — shard_guild_members, the guild.roster/guild.leave ingest, the kind→feature map entries — and stopped there. It never named the pin: the version the website tells the sidecar it speaks, declared twice in that module (DEFAULT_PROTOCOL and the uo_link_config.protocol column default).

Both stayed at 3 when protocol 4 shipped. A fresh install then spoke 3 to a protocol-4 sidecar, which 409s rather than mis-parsing — so the deployment read nothing from its shard until an admin edited the number by hand. Existing installs were fine, because their stored row had already been moved by the protocol-3 one-shot and the stored row wins, which is precisely why nobody saw it.

Found while standing up a demo deployment for the marketing site's screenshots.

What changes

the module-uo row gains the pinned protocol → 4
a paragraph after the overlay.toml note recording the fourth declaration site, what its omission actually cost, and why the failure was invisible on existing installs

Code half: Module-uo PR — the pin, plus a protocol-4 one-shot mirroring the protocol-3 one.

AI-assisted: written with Claude Code (Claude Opus).

Co-Authored-By: Claude <noreply@anthropic.com>

## Why `v4.md` §5's cross-repo obligation table gave `module-uo` one row — `shard_guild_members`, the `guild.roster`/`guild.leave` ingest, the kind→feature map entries — and stopped there. It never named the **pin**: the version the website tells the sidecar it speaks, declared twice in that module (`DEFAULT_PROTOCOL` and the `uo_link_config.protocol` column default). Both stayed at 3 when protocol 4 shipped. A fresh install then spoke 3 to a protocol-4 sidecar, which `409`s rather than mis-parsing — so the deployment read *nothing* from its shard until an admin edited the number by hand. Existing installs were fine, because their stored row had already been moved by the protocol-3 one-shot and the stored row wins, which is precisely why nobody saw it. Found while standing up a demo deployment for the marketing site's screenshots. ## What changes - the `module-uo` row gains **the pinned protocol → 4** - a paragraph after the `overlay.toml` note recording the fourth declaration site, what its omission actually cost, and why the failure was invisible on existing installs Code half: `Module-uo` PR — the pin, plus a protocol-4 one-shot mirroring the protocol-3 one. --- - [x] AI-assisted: written with Claude Code (Claude Opus). Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude added 1 commit 2026-08-25 00:24:14 +00:00

fix(link): a protocol bump owes four declaration sites, not three 36f8e1071d

v4's cross-repo obligation table named module-uo's ingest work and stopped
there, so both of that module's PIN sites — DEFAULT_PROTOCOL and the
uo_link_config.protocol column default — stayed at 3 when protocol 4 shipped.

The consequence is not partial degradation. A sidecar answers a stale client
`409 protocol version mismatch` rather than mis-parsing it, so a fresh install
read nothing at all from its shard — empty marketplace, empty guild board, no
status — until an admin edited the number by hand in Admin → Shard. Existing
installs were unaffected, which is why it went unnoticed: their stored row had
already been moved by the protocol-3 one-shot, and the stored row wins.

Found while standing up a demo deployment for the marketing site's screenshots;
fixed in Module-uo.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit e719c3c32e into main

2026-08-25 00:34:06 +00:00

whitlocktech deleted branch fix/protocol-4-module-pin

2026-08-25 00:34:07 +00:00

whitlocktech referenced this issue from a commit

2026-08-25 00:34:08 +00:00

Merge pull request 'fix(link): a protocol bump owes four declaration sites, not three' (#175) from fix/protocol-4-module-pin into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#175