docs(link): the Protocol 3.0 cutover (v3.md order 6) #72

wtclaude · 2026-07-29T23:05:57Z

wtclaude commented

2026-07-29 23:05:57 +00:00

What & why

Order 6 of the Protocol 3.0 plan (v3.md §4) — the docs half of the cutover, paired with link #20 and website #117.

INTEGRATION.md was written for the window that just closed. Its version section told integrators the version had not been bumped yet, that a sidecar on edge still reports 2 while already carrying v3 kinds, and that they must not infer feature availability from the version number during that window. All of that is now wrong in the direction that matters — an integrator reading it would pin 2 and get a 409 on every call. So §2 now states 3 (header, /health, ws.hello, the 409 example, and the §8 worked example), and the "until then" paragraph is replaced by what a v2 integration actually has to do: change the constant it sends, and nothing else, because nothing that existed in v2 changed shape.

v3.md gains §4.1 — the five places the version lives, and, more usefully, why the website's boot migration is gated on a marker row in settings. schema.sql re-runs on every boot and uo_link_config.protocol is admin-editable, so an ungated UPDATE would silently un-pin an operator running an older sidecar. That reasoning is the one part of the cutover a reader could not infer from the code, which is otherwise a single constant.

PLAN.md picks up the closing sentence on 3.0's phasing. Progress tables: 5b → Done, 6 → In review.

How it was tested

Prose only. Cross-checked against the code being described rather than the plan: PROTOCOL_VERSION = 3 (link #20), the migration SQL quoted in §4.1 is the statement as committed (website #117), and the 409 body in §2 is the sidecar's real response, copied from a live call to the release binary.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code. I have reviewed and understand
every change, and take responsibility for it. AI-authored commits are
marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license
(GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why **Order 6 of the Protocol 3.0 plan ([`v3.md`](link/v3.md) §4) — the docs half of the cutover**, paired with link [#20](https://gitea.whitlocktech.com/RunicGateway/link/pulls/20) and website [#117](https://gitea.whitlocktech.com/RunicGateway/website/pulls/117). **`INTEGRATION.md` was written for the window that just closed.** Its version section told integrators the version had *not* been bumped yet, that a sidecar on `edge` still reports `2` while already carrying v3 kinds, and that they must not infer feature availability from the version number during that window. All of that is now wrong in the direction that matters — an integrator reading it would pin `2` and get a 409 on every call. So §2 now states **3** (header, `/health`, `ws.hello`, the 409 example, and the §8 worked example), and the "until then" paragraph is replaced by what a v2 integration actually has to do: change the constant it sends, and nothing else, because nothing that existed in v2 changed shape. **`v3.md` gains §4.1** — the five places the version lives, and, more usefully, *why* the website's boot migration is gated on a marker row in `settings`. `schema.sql` re-runs on every boot and `uo_link_config.protocol` is admin-editable, so an ungated `UPDATE` would silently un-pin an operator running an older sidecar. That reasoning is the one part of the cutover a reader could not infer from the code, which is otherwise a single constant. `PLAN.md` picks up the closing sentence on 3.0's phasing. Progress tables: 5b → Done, 6 → In review. ## How it was tested Prose only. Cross-checked against the code being described rather than the plan: `PROTOCOL_VERSION = 3` (link #20), the migration SQL quoted in §4.1 is the statement as committed (website #117), and the 409 body in §2 is the sidecar's real response, copied from a live call to the release binary. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-07-29 23:05:59 +00:00

docs(link): the Protocol 3.0 cutover (v3.md order 6) 71207cef16

INTEGRATION.md was written for the window that just closed -- it told integrators
the version had NOT been bumped yet and that a sidecar on `edge` reports 2 while
already carrying v3 kinds. That guidance is now wrong in the direction that
matters, so the version section states 3 (header, /health, ws.hello, the 409
example and the §8 worked example) and replaces the "until then" paragraph with
what a v2 integration actually has to do to upgrade: change the constant it
sends, and nothing else, because nothing that existed in v2 changed shape.

v3.md gains §4.1 for what the bump touches and, more importantly, WHY the
website's boot migration is gated on a marker row: schema.sql is re-run on every
boot and uo_link_config.protocol is admin-editable, so an ungated UPDATE would
silently un-pin an operator running an older sidecar. That is the one piece of
the cutover a reader could not infer from the code being one constant.

Progress tables: 5b done, 6 in review.

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

wtclaude referenced this pull request from RunicGateway/link

2026-07-29 23:07:14 +00:00

feat(sidecar)!: Protocol 3.0 cutover — X-UOLink-Version 2 → 3 #21

wtclaude referenced this pull request from RunicGateway/website

2026-07-29 23:07:57 +00:00

feat(shard)!: Protocol 3.0 cutover — visibility framework, spawn atlas, marketplace #118

wtclaude referenced this pull request

2026-07-29 23:09:05 +00:00

docs!: Protocol 3.0 cutover — the 3.0 documentation set #73

wtclaude added 1 commit 2026-07-29 23:09:56 +00:00

docs(link): fill in the cutover PR numbers 32def88c4e

The order-6 row was written before the seven PRs existed. Same follow-up as the
cliloc row got.

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

whitlocktech merged commit 3a1bbdd165 into edge

2026-07-30 03:03:14 +00:00

whitlocktech deleted branch docs/protocol-3-cutover

2026-07-30 03:03:14 +00:00

whitlocktech referenced this issue from a commit

2026-07-30 03:03:16 +00:00

Merge pull request 'docs(link): the Protocol 3.0 cutover (v3.md order 6)' (#72) from docs/protocol-3-cutover into edge

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#72