docs(modules): module-rust phase 1 as built — the transport, and three org-lead decisions #252

wtclaude · 2026-09-16T00:58:27Z

wtclaude commented

2026-09-16 00:58:27 +00:00

Adds docs/rust-link/, the canonical spec for the Rust bridge, and records phase 1 in modules/rust/PLAN.md as §13.

Lands with Rust-Link#1, Rust-Plugins#1 and Module-Rust#1 — the four are one change across four repos.

`docs/rust-link/`

PROTOCOL.md — canonical. The game link and the website API, the four declaration sites of the wire version and why they are enforced differently on each half, and everything protocol 1 defines.
INTEGRATION.md — standing the bridge up by hand, and which of the three components is wrong when it does not work.

Three org-lead decisions, none settled by §2

D1 — the bridge docs live at docs/rust-link/, a new top-level directory mirroring docs/link/ rather than sitting under modules/rust/. Keeps the uo/link symmetry and keeps module docs separate from bridge docs.
D2 — loopback is the ONLY trust boundary on the game link, no token, exactly as on the ServUO bridge. Argued the other way on the grounds that Rust servers are far more often on GSPs than ServUO shards are; overruled, and the consequence is now written down as the mistake rather than defended against.
D3 — the plugin reads Oxide's own config file, so it lands inside the phase-7b config editor for free. The argument against — that editing Host/Port from the website could cut the link carrying the edit — becomes that phase's guard rather than a reason for a second config mechanism.

§11.3 is corrected in place

It read module.json's extensions array as held against reality by the loader the way mounts is. Only half true. The loader checks that a named slot exists and never that the module filled it — checkDeclared covers mounts alone — and only one of R13's two slots can be declared there at all, because site.footer.status is a client slot and naming it fails the load outright.

§13.3 — five defects a running server found that no test could

Including a bootId that regenerated on every plugin load rather than every server start, which would have asked core to reconcile its whole ledger on every oxide.reload, for a world that never moved. And a four-connection SQLite pool over :memory: handing out four empty databases.

The phase-0 lesson repeating: a plan claim derived from reading source is provisional until a rig agrees.

§13.4 — two corrections owed back to the Integration Kit

Both recorded for phase 19, and both are the kit being right about the general case and specific about the wrong detail. The kit was also right in a way worth keeping: noGameConnection.test.js's header predicts the exact failure a module adding a sidecar client will hit and names the one-line fix, which is what happened.

This contribution was AI-assisted (Claude Code).

🤖 Generated with Claude Code

https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

Adds **`docs/rust-link/`**, the canonical spec for the Rust bridge, and records phase 1 in `modules/rust/PLAN.md` as §13. Lands with [Rust-Link#1](https://gitea.whitlocktech.com/RunicGateway/Rust-Link/pulls/1), [Rust-Plugins#1](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins/pulls/1) and [Module-Rust#1](https://gitea.whitlocktech.com/RunicGateway/Module-Rust/pulls/1) — the four are one change across four repos. ## `docs/rust-link/` - **`PROTOCOL.md`** — canonical. The game link and the website API, the four declaration sites of the wire version and why they are enforced differently on each half, and everything protocol 1 defines. - **`INTEGRATION.md`** — standing the bridge up by hand, and which of the three components is wrong when it does not work. ## Three org-lead decisions, none settled by §2 - **D1 — the bridge docs live at `docs/rust-link/`**, a new top-level directory mirroring `docs/link/` rather than sitting under `modules/rust/`. Keeps the `uo`/`link` symmetry and keeps module docs separate from bridge docs. - **D2 — loopback is the ONLY trust boundary on the game link**, no token, exactly as on the ServUO bridge. Argued the other way on the grounds that Rust servers are far more often on GSPs than ServUO shards are; **overruled**, and the consequence is now written down as the mistake rather than defended against. - **D3 — the plugin reads Oxide's own config file**, so it lands inside the phase-7b config editor for free. The argument against — that editing `Host`/`Port` from the website could cut the link carrying the edit — becomes that phase's guard rather than a reason for a second config mechanism. ## §11.3 is corrected in place It read `module.json`'s `extensions` array as held against reality by the loader the way `mounts` is. **Only half true.** The loader checks that a named slot *exists* and never that the module filled it — `checkDeclared` covers `mounts` alone — and only **one** of R13's two slots can be declared there at all, because `site.footer.status` is a client slot and naming it fails the load outright. ## §13.3 — five defects a running server found that no test could Including a `bootId` that regenerated on every *plugin* load rather than every *server* start, which would have asked core to reconcile its whole ledger on every `oxide.reload`, for a world that never moved. And a four-connection SQLite pool over `:memory:` handing out four empty databases. The phase-0 lesson repeating: a plan claim derived from reading source is provisional until a rig agrees. ## §13.4 — two corrections owed back to the Integration Kit Both recorded for phase 19, and both are the kit being right about the general case and specific about the wrong detail. The kit was also right in a way worth keeping: `noGameConnection.test.js`'s header predicts the exact failure a module adding a sidecar client will hit and names the one-line fix, which is what happened. --- - [x] This contribution was AI-assisted (Claude Code). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

wtclaude added 1 commit 2026-09-16 00:58:29 +00:00

docs(modules): module-rust phase 1 as built — the transport, and three org-lead decisions bd83b34614

Adds docs/rust-link/, the canonical spec for the Rust bridge: PROTOCOL.md (the
game link and the website API) and INTEGRATION.md (standing it up by hand, and
which of the three components is wrong when it does not work). A new top-level
directory mirroring link/, which is decision D1 below — it keeps the uo/link
symmetry and keeps module docs separate from bridge docs.

Records phase 1 in PLAN.md as section 13. Both criteria met: a server.hello
produced by the live Rust rig travelled game → sidecar → module → the public
website API, killing the sidecar left the game untouched, and all five guards are
green on the module skeleton.

Three org-lead decisions this phase needed, none settled by section 2:

* D1 — the bridge docs live at docs/rust-link/.
* D2 — loopback is the ONLY trust boundary on the game link, no token, exactly
  as on the ServUO bridge. Argued the other way on the grounds that Rust servers
  are far more often on GSPs; overruled, and the consequence is now written down
  as the mistake rather than defended against.
* D3 — the plugin reads Oxide's own config file, so it lands inside the phase-7b
  config editor for free. The argument against — that editing Host/Port from the
  website could cut the link carrying the edit — becomes that phase's guard
  rather than a reason for a second config mechanism.

Section 11.3 is corrected in place: it read module.json's "extensions" array as
held against reality by the loader in the way "mounts" is. Only half true. The
loader checks that a named slot EXISTS and never that the module filled it —
checkDeclared covers "mounts" alone — and only ONE of R13's two slots can be
declared there at all, because site.footer.status is a CLIENT slot and naming it
fails the load outright.

Section 13.3 records five defects a running server found that no test could,
including a bootId that regenerated on every plugin load rather than every server
start — which would have asked core to reconcile its whole ledger on every
oxide.reload, for a world that never moved.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

whitlocktech merged commit b4b05b4108 into main

2026-09-16 01:29:57 +00:00

whitlocktech deleted branch docs/rust-phase-1

2026-09-16 01:29:58 +00:00

whitlocktech referenced this issue from a commit

2026-09-16 01:29:59 +00:00

Merge pull request 'docs(modules): module-rust phase 1 as built — the transport, and three org-lead decisions' (#252) from docs/rust-phase-1 into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#252