docs(site): the engagement system — cutover 7 of 7 (edgemain) #28

Merged
whitlocktech merged 17 commits from edge into main 2026-09-01 18:04:23 +00:00
2 changed files with 15 additions and 12 deletions
Showing only changes of commit 391a4a131b - Show all commits

View File

@@ -4,12 +4,13 @@ description: One number, declared in three repositories, that decides whether a
--- ---
import { Aside } from '@astrojs/starlight/components'; import { Aside } from '@astrojs/starlight/components';
import platform from '../../../../data/platform.json';
The loopback wire protocol between the game plugin and the sidecar is a **versioned The loopback wire protocol between the game plugin and the sidecar is a **versioned
compatibility contract**, not a build dependency. Nothing compiles the three sides together, compatibility contract**, not a build dependency. Nothing compiles the three sides together,
so the number is what stops a mismatch from being discovered as corrupted data. so the number is what stops a mismatch from being discovered as corrupted data.
The current protocol is **4**. The current protocol is **{platform.protocol}**.
## Three declaration sites ## Three declaration sites
@@ -17,8 +18,8 @@ The same number is written down in three places, and they must move together.
| Where | What declares it | | Where | What declares it |
|---|---| |---|---|
| `link/sidecar/src/main.rs` | `pub const PROTOCOL_VERSION: u32 = 4` — what the sidecar speaks | | `link/sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.protocol} — what the sidecar speaks |
| `servuo-plugins/overlay.toml` | `protocol = 4` — what the plugin overlay speaks | | `servuo-plugins/overlay.toml` | `protocol`, currently {platform.protocol} — what the plugin overlay speaks |
| The bundle manifest | Copied from `overlay.toml` by CI, so a released pair carries its own claim | | The bundle manifest | Copied from `overlay.toml` by CI, so a released pair carries its own claim |
<Aside type="caution" title="Bump the overlay in the same PR as the emitters"> <Aside type="caution" title="Bump the overlay in the same PR as the emitters">
@@ -44,19 +45,19 @@ allowed to be chosen independently.
## What a bump obliges ## What a bump obliges
Changing a message shape means editing every side plus the specification. A protocol-4 Changing a message shape means editing every side plus the specification. The most recent
change touched: bump touched:
| Repository | What had to change | | Repository | What had to change |
|---|---| |---|---|
| `servuo-plugins` | The emitters, the config keys, and `overlay.toml` | | `servuo-plugins` | The emitters, the config keys, and `overlay.toml` |
| `link` | `PROTOCOL_VERSION`, a store migration, and the projections | | `link` | `PROTOCOL_VERSION`, and the projections |
| `module-uo` | The tables, the ingest, and the kind-to-feature map | | `module-uo` | The tables, the ingest, and the kind-to-feature map |
| `docs` | The protocol document and the integration guide | | `docs` | The protocol document and the integration guide |
Note `link`'s entry: **a protocol bump can require a store migration**, because the sidecar **A protocol bump can also require a store migration**, because the sidecar persists what it
persists what it forwards. That is not automatic, and version 4 was the first bump that forwards. That is not automatic version 4 needed one and version 5 did not, because
needed one. version 5 only widened frames the store already keeps whole.
## This is not the module API version ## This is not the module API version
@@ -92,8 +93,10 @@ What is worth inheriting is the **shape**:
## Canonical documents ## Canonical documents
[`link/v5.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v5.md)
is the current protocol's record, including its cross-repository obligations, and
[`link/v4.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v4.md) [`link/v4.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v4.md)
is the protocol-4 record, including its cross-repository obligations; the one before it;
[`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md) [`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md)
§7 is the wire protocol, and §7 is the wire protocol, and
[`link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md) [`link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md)

View File

@@ -14,9 +14,9 @@
"verifiedOn": "2026-08-19", "verifiedOn": "2026-08-19",
"protocol": 4, "protocol": 5,
"moduleApi": "1.6.0", "moduleApi": "1.9.0",
"bundle": { "bundle": {
"tag": "2026.08.19", "tag": "2026.08.19",