docs(modules): settle Phase 5 — the Integration Kit, and the sidecar rule #145

wtclaude · 2026-08-12T14:38:43Z

wtclaude commented

2026-08-12 14:38:43 +00:00

Phase 4 closed on 2026-08-12 (website#146, docs#144). This settles Phase 5 — the Integration Kit, RunicGateway/Integration-kit, which is still an empty repo with no branches.

Pairs with website#147 (the MODULE_API_VERSION 1.4.0 bump, into edge). Either order.

Six decisions, settled by the org lead

The kit ships a buildable template/, not prose alone — a module that really compiles and really loads, so the acceptance test asks for a working module rather than an understood one.
CI is the anti-rot mechanism: clone website at a pinned ref, assert the kit's coreApi equals that core's MODULE_API_VERSION, build the template and run its guards, link-check the book. A contract bump then breaks the kit's build loudly — the mechanised form of §2.11's own fear.
The sidecar is the default and only path to a game. A non-blocking dumb forwarder that persists before it forwards, so a website that is down or restarting loses nothing and a page shows the last thing the game said. A game that already ships a remote-control surface gets a thin sidecar, not none.
That is contract, not advice — MODULE_API §2.7, MODULE_API_VERSION 1.4.0.
Acceptance gets a cold-agent proxy now and a draft banner until a person outside the org replaces it.
rust-dryrun.md is corrected with a dated note, not silently rewritten.

What changed

website/MODULE_SYSTEM.md

§2.11.1 (new) — Phase 5's shape: measured starting state, the six decisions with their reasoning and costs, the four-slice table, the acceptance mechanism.
§2.11 — layer 2 rewritten around decision 3.
§2.10 — a MODULE_API_VERSION bump now carries a pass over the kit. CI fails on the version number, which is the half a machine can check; whether a chapter has become untrue is the author's obligation in the same PR.
Part 3 — decisions 28–33.
The Phase 5 line in Part 2's phase list: STARTED 2026-08-12.

website/MODULE_API.md

§2.7 gains one prohibition — a module does not open a connection to a game server from the website process (a game socket, RCON, a query port, an engine admin API) — with the three reasons: the website is the internet-facing process and the game is not; the sidecar owns the durable copy; neither side can stall the other. Flagged explicitly as normative prose with no CI behind it, since an outbound socket is not statically detectable the way an internal require is (§5.1).
§1.1 — the 1.4.0 entry. No member added, removed or changed; minor deliberately, and module-uo's coreApi: "^1.3.0" still resolves.

modules/rust-dryrun.md

§2 "Talking to the game" went from "No sidecar" to a thin RCON sidecar — RCON on the game side, the uo-link-shaped HTTP+WS API and a SQLite store on the website side — because RCON is a live channel with no memory, and a wipe is the moment the game forgets. Carries a dated Correction note recording what the exercise originally concluded and why it was overruled: it was not wrong about ServUO, it mistook the shard-dials-out invariant for the whole reason a sidecar exists.

Two things verified rather than assumed

The durable-store claim is true of uo-link today, not aspirational: link/sidecar/src/store.rs persists event history, each board's latest snapshot, the economy series and the published ruleset, and REST reads are served from it — "a rules page that goes blank when the shard restarts is worse than a stale one". The live WS feed is explicitly lossy (ws client lagged; dropping missed events), which is why durability is the store's job and not the socket's.
The module system is on edge, not main — main has no server/src/modules/ at all. So the kit's pinned core ref must point at edge, and that pin is one of the things decision 11's cutover has to revisit. Recorded in §2.11.1, because a pinned ref quietly aimed at an abandoned branch is exactly the failure this kit is meant to be immune to.

Checks

Documentation only. The paired code change (website#147) passes 742 server + 187 client tests, and routes.manifest.json + swagger-output.json regenerate byte-identical.

AI-assisted: written with Claude Code (Claude Opus), reviewed by the author.

🤖 Generated with Claude Code

https://claude.ai/code/session_018ocYxQWk3EhZe5gWRJXFU8

Phase 4 closed on 2026-08-12 (website#146, docs#144). This settles **Phase 5 — the Integration Kit**, `RunicGateway/Integration-kit`, which is still an empty repo with no branches. Pairs with **website#147** (the `MODULE_API_VERSION` 1.4.0 bump, into `edge`). Either order. ## Six decisions, settled by the org lead 1. **The kit ships a buildable `template/`**, not prose alone — a module that really compiles and really loads, so the acceptance test asks for a working module rather than an understood one. 2. **CI is the anti-rot mechanism**: clone `website` at a pinned ref, assert the kit's `coreApi` **equals** that core's `MODULE_API_VERSION`, build the template and run its guards, link-check the book. A contract bump then breaks the kit's build loudly — the mechanised form of §2.11's own fear. 3. **The sidecar is the default and only path to a game.** A non-blocking dumb forwarder that **persists before it forwards**, so a website that is down or restarting loses nothing and a page shows the last thing the game said. A game that already ships a remote-control surface gets a *thin* sidecar, not none. 4. **That is contract, not advice** — MODULE_API §2.7, `MODULE_API_VERSION` **1.4.0**. 5. **Acceptance gets a cold-agent proxy now and a draft banner** until a person outside the org replaces it. 6. **`rust-dryrun.md` is corrected with a dated note**, not silently rewritten. ## What changed **`website/MODULE_SYSTEM.md`** - **§2.11.1 (new)** — Phase 5's shape: measured starting state, the six decisions with their reasoning and costs, the four-slice table, the acceptance mechanism. - **§2.11** — layer 2 rewritten around decision 3. - **§2.10** — a `MODULE_API_VERSION` bump now carries a pass over the kit. CI fails on the version number, which is the half a machine can check; whether a chapter has become untrue is the author's obligation in the same PR. - **Part 3** — decisions 28–33. - The Phase 5 line in Part 2's phase list: **STARTED 2026-08-12**. **`website/MODULE_API.md`** - **§2.7** gains one prohibition — a module does not open a connection to a game server from the website process (a game socket, RCON, a query port, an engine admin API) — with the three reasons: the website is the internet-facing process and the game is not; the sidecar owns the durable copy; neither side can stall the other. Flagged explicitly as **normative prose with no CI behind it**, since an outbound socket is not statically detectable the way an internal `require` is (§5.1). - **§1.1** — the 1.4.0 entry. No member added, removed or changed; minor deliberately, and `module-uo`'s `coreApi: "^1.3.0"` still resolves. **`modules/rust-dryrun.md`** - §2 "Talking to the game" went from **"No sidecar"** to a thin RCON sidecar — RCON on the game side, the uo-link-shaped HTTP+WS API and a SQLite store on the website side — because RCON is a live channel with no memory, and a wipe is the moment the game forgets. Carries a dated **Correction** note recording what the exercise originally concluded and why it was overruled: it was not wrong about ServUO, it mistook the shard-dials-out invariant for the whole reason a sidecar exists. ## Two things verified rather than assumed - **The durable-store claim is true of `uo-link` today**, not aspirational: `link/sidecar/src/store.rs` persists event history, each board's latest snapshot, the economy series and the published ruleset, and REST reads are served from it — *"a rules page that goes blank when the shard restarts is worse than a stale one"*. The live WS feed is explicitly lossy (`ws client lagged; dropping missed events`), which is why durability is the store's job and not the socket's. - **The module system is on `edge`, not `main`** — `main` has no `server/src/modules/` at all. So the kit's pinned core ref must point at `edge`, and that pin is one of the things decision 11's cutover has to revisit. Recorded in §2.11.1, because a pinned ref quietly aimed at an abandoned branch is exactly the failure this kit is meant to be immune to. ## Checks Documentation only. The paired code change (website#147) passes 742 server + 187 client tests, and `routes.manifest.json` + `swagger-output.json` regenerate byte-identical. --- - [x] AI-assisted: written with Claude Code (Claude Opus), reviewed by the author. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_018ocYxQWk3EhZe5gWRJXFU8

wtclaude added 1 commit 2026-08-12 14:38:44 +00:00

docs(modules): settle Phase 5 — the Integration Kit, and the sidecar rule 89aff5c26b

Phase 4 closed; this is the plan for Phase 5, the Integration Kit, settled with
the org lead on six decisions.

MODULE_SYSTEM.md
- §2.11.1 (new): Phase 5's shape — measured starting state, the six decisions,
  the four slices, the acceptance mechanism.
- §2.11: layer 2 rewritten. The sidecar is the default and only path to a game,
  and it is a non-blocking dumb forwarder that persists before it forwards. A
  game that already ships a remote-control surface gets a thin sidecar, not none.
- §2.10: a MODULE_API_VERSION bump now carries a pass over the kit.
- Part 3: decisions 28–33.
- The Phase 5 line in Part 2's phase list: STARTED 2026-08-12.

MODULE_API.md
- §2.7 gains one prohibition: a module does not open a connection to a game
  server from the website process — a game socket, RCON, a query port, an
  engine admin API — with the three reasons it exists (the website is the
  internet-facing process, the sidecar owns the durable copy, neither side can
  stall the other). Normative prose with no CI behind it, stated so that every
  second module does not re-decide it.
- §1.1: the 1.4.0 entry. No member changed; minor deliberately.

modules/rust-dryrun.md
- §2 "Talking to the game" rewritten from "No sidecar" to a thin RCON sidecar,
  with a dated Correction note recording what the exercise originally concluded
  and why it was overruled. Corrected in view rather than silently rewritten.

Pairs with website#… (the 1.4.0 bump, into edge); either order.

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

whitlocktech merged commit 5badb91a96 into main

2026-08-12 14:40:56 +00:00

whitlocktech deleted branch docs/module-phase5-plan

2026-08-12 14:40:57 +00:00

whitlocktech referenced this issue from a commit

2026-08-12 14:40:58 +00:00

Merge pull request 'docs(modules): settle Phase 5 — the Integration Kit, and the sidecar rule' (#145) from docs/module-phase5-plan into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#145